monorepo-navigator

---
name: monorepo-navigator
description: Use when navigating, optimizing, or troubleshooting monorepos with Turborepo, Nx, pnpm, Lerna; includes impact analysis, selective builds, caching, and multi-repo migrations.
category: Engineering
version: 1.0.0
tools: []
---

# Monorepo Navigator

**Tier:** POWERFUL  
**Domain:** Monorepo Architecture / Build Systems

Navigate, manage, and optimize monorepos using Turborepo, Nx, pnpm workspaces, Lerna, and Changesets. Enable cross-package impact analysis, selective builds/tests on affected packages, remote caching, dependency graph visualization, and structured migrations.

## Core Capabilities

- **Cross-package impact analysis** — determine which apps break when a shared package changes
- **Selective commands** — run tests/builds only for affected packages
- **Dependency graph** — visualize package relationships as diagrams
- **Build optimization** — remote caching, incremental builds, parallel execution
- **Migration** — multi-repo → monorepo with zero history loss
- **Publishing** — Changesets for versioning, pre-release channels, npm workflows

## Tool Selection

| Tool | Best For | Key Feature |
|---|---|---|
| **Turborepo** | JS/TS monorepos | Best-in-class remote caching |
| **Nx** | Large enterprises, plugins | Project graph, code generation |
| **pnpm workspaces** | Workspace protocol | `workspace:*` for local refs |
| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |
| **Changesets** | Modern versioning | Changelog generation, pre-release channels |

## Common Pitfalls

| Pitfall | Fix |
|---|---|
| Running without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |
| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — replaces `workspace:*` automatically |
| All packages rebuild on unrelated changes | Tune `inputs` in config to exclude docs, config files |
| Shared config breaks all type-checks | Use `extends` properly; each package overrides `rootDir` / `outDir` |
| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging |
| Remote cache not working in CI | Check env vars; verify with `--summarize` |
| CLAUDE.md too generic | Add explicit per-package rules |

## Best Practices

1. **Root CLAUDE.md defines the map** — document every package and dependency rules
2. **Per-package CLAUDE.md defines rules** — what's allowed, what's forbidden, test commands
3. **Always scope commands with --filter** — running everything defeats the purpose
4. **Remote cache is not optional** — without it, CI is slower than multi-repo
5. **Changesets over manual versioning** — never hand-edit package.json versions
6. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js
7. **Impact analysis before merging shared changes** — communicate blast radius
8. **packages/types as pure TypeScript** — no runtime code, no dependencies