Monorepo Navigator

# 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 ```bash 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 1. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules 2. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands 3. **Always scope commands with --filter** — running everything on every change defeats the purpose 4. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI 5. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo 6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js 7. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius 8. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check