Monorepo Navigator
The Monorepo Navigator skill helps manage and optimize monorepos using tools like Turborepo and Nx. It enables impact analysis, selective builds/tests,
Install
npx promptshop add monorepo-navigatorDetails
What This Skill Does
- The Monorepo Navigator skill helps manage and optimize monorepos using tools like Turborepo and Nx.
- It enables impact analysis, selective builds/tests, dependency graph visualization, and structured migrations.
- This skill is ideal for teams managing multiple packages/apps sharing code.
When to Use
- Multiple packages share code.
- Build times are slow.
- Migrating to a monorepo.
- Publishing packages to npm.
- Teams need unified tooling.
Key Features
- Cross-package impact analysis.
- Selective commands for affected packages.
- Dependency graph visualization.
- Build optimization with remote caching.
- Multi-repo to monorepo migration.
- Workspace-aware Claude Code config.
Monorepo Navigator
Tier: POWERFUL
Category: Engineering
Domain: Monorepo Architecture / Build Systems
Overview
- Navigate, manage, and optimize monorepos.
- Covers Turborepo, Nx, pnpm workspaces, and Lerna.
- Enables cross-package impact analysis, selective builds/tests on affected packages only, remote caching, dependency graph visualization, and structured migrations from multi-repo to monorepo.
- Includes Claude Code configuration for workspace-aware development.
Core Capabilities
Cross-package impact analysis — determine which apps break when a shared package changes Selective commands — run tests/builds only for affected packages (not everything) Dependency graph — visualize package relationships as Mermaid diagrams Build optimization — remote caching, incremental builds, parallel execution Migration — step-by-step multi-repo → monorepo with zero history loss Publishing — changesets for versioning, pre-release channels, npm publish workflows Claude Code config — workspace-aware CLAUDE.md with per-package instructions
When to Use
Use when: Multiple packages/apps share code (UI components, utils, types, API clients) Build times are slow because everything rebuilds when anything changes Migrating from multiple repos to a single repo Need to publish packages to npm with coordinated versioning Teams work across multiple packages and need unified tooling
Skip when: Single-app project with no shared packages Team/project boundaries are completely isolated (polyrepo is fine) Shared code is minimal and copy-paste overhead is acceptable
Tool Selection
| Tool | Best For | Key Feature |
|---|---|---|
Turborepo
| JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config | | Nx | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands | | pnpm workspaces | Workspace protocol, disk efficiency | workspace:* for local package refs | | Lerna | npm publishing, versioning | Batch publishing, conventional commits | | Changesets | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |
Most modern setups: pnpm workspaces + Turborepo + Changesets
Turborepo → See references/monorepo-tooling-reference.md for details
Workspace Analyzer
python3 scripts/monorepo_analyzer.py /path/to/monorepo python3 scripts/monorepo_analyzer.py /path/to/monorepo --json
Also see references/monorepo-patterns.md for common architecture and CI patterns.
Common Pitfalls
| Pitfall | Fix |
|---|---|
| Running turbo run build without --filter on every PR | Always use --filter=...[origin/main] in CI |
| workspace: refs cause publish failures | Use pnpm changeset publish — it replaces workspace: with real versions automatically |
| All packages rebuild when unrelated file changes | Tune inputs in turbo.json to exclude docs, config files from cache keys |
| Shared tsconfig causes one package to break all type-checks | Use extends properly — each package extends root but overrides rootDir / outDir |
| git history lost during migration | Use git filter-repo --to-subdirectory-filter before merging — never move files manually |
| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with turbo run build --summarize |
| CLAUDE.md too generic — Claude modifies wrong package | Add explicit "When working on X, only touch files in apps/X" rules per package CLAUDE.md |
Best Practices
Root CLAUDE.md defines the map — document every package, its purpose, and dependency rules Per-package CLAUDE.md defines the rules — what's allowed, what's forbidden, testing commands Always scope commands with --filter — running everything on every change defeats the purpose Remote cache is not optional — without it, monorepo CI is slower than multi-repo CI Changesets over manual versioning — never hand-edit package.json versions in a monorepo Shared configs in root, extended in packages — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js Impact analysis before merging shared package changes — run affected check, communicate blast radius Keep packages/types as pure TypeScript — no runtime code, no dependencies, fast to build and type-checkMonorepo Navigator
Tier: POWERFUL
Category: Engineering
Domain: Monorepo Architecture / Build Systems