Note: Bundled scripts ship as Markdown reference (.md) — copy the code out of the .md file to run it.
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-check
Creator: Engineering
License: MIT
Source Repo: neekware/dojo-skills
Source Bucket: engineering
Original Path: engineering/monorepo-navigator
1---2name: monorepo-navigator-23description: > **Note:** Bundled scripts ship as Markdown reference (`.md`) — copy the code out of the `.md` file to run it.4---5> **Note:** Bundled scripts ship as Markdown reference (`.md`) — copy the code out of the `.md` file to run it.67# Monorepo Navigator89**Tier:** POWERFUL 10**Category:** Engineering 11**Domain:** Monorepo Architecture / Build Systems1213---1415## Overview1617Navigate, 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.1819---2021## Core Capabilities2223- **Cross-package impact analysis** — determine which apps break when a shared package changes24- **Selective commands** — run tests/builds only for affected packages (not everything)25- **Dependency graph** — visualize package relationships as Mermaid diagrams26- **Build optimization** — remote caching, incremental builds, parallel execution27- **Migration** — step-by-step multi-repo → monorepo with zero history loss28- **Publishing** — changesets for versioning, pre-release channels, npm publish workflows29- **Claude Code config** — workspace-aware CLAUDE.md with per-package instructions3031---3233## When to Use3435Use when:3637- Multiple packages/apps share code (UI components, utils, types, API clients)38- Build times are slow because everything rebuilds when anything changes39- Migrating from multiple repos to a single repo40- Need to publish packages to npm with coordinated versioning41- Teams work across multiple packages and need unified tooling4243Skip when:4445- Single-app project with no shared packages46- Team/project boundaries are completely isolated (polyrepo is fine)47- Shared code is minimal and copy-paste overhead is acceptable4849---5051## Tool Selection5253| Tool | Best For | Key Feature |54| ------------------- | ---------------------------------------- | ------------------------------------------------- |55| **Turborepo** | JS/TS monorepos, simple pipeline config | Best-in-class remote caching, minimal config |56| **Nx** | Large enterprises, plugin ecosystem | Project graph, code generation, affected commands |57| **pnpm workspaces** | Workspace protocol, disk efficiency | `workspace:*` for local package refs |58| **Lerna** | npm publishing, versioning | Batch publishing, conventional commits |59| **Changesets** | Modern versioning (preferred over Lerna) | Changelog generation, pre-release channels |6061Most modern setups: **pnpm workspaces + Turborepo + Changesets**6263---6465## Turborepo6667→ See references/monorepo-tooling-reference.md for details6869## Workspace Analyzer7071```bash72python3 scripts/monorepo_analyzer.py /path/to/monorepo73python3 scripts/monorepo_analyzer.py /path/to/monorepo --json74```7576Also see `references/monorepo-patterns.md` for common architecture and CI patterns.7778## Common Pitfalls7980| Pitfall | Fix |81| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- |82| Running `turbo run build` without `--filter` on every PR | Always use `--filter=...[origin/main]` in CI |83| `workspace:*` refs cause publish failures | Use `pnpm changeset publish` — it replaces `workspace:*` with real versions automatically |84| All packages rebuild when unrelated file changes | Tune `inputs` in turbo.json to exclude docs, config files from cache keys |85| Shared tsconfig causes one package to break all type-checks | Use `extends` properly — each package extends root but overrides `rootDir` / `outDir` |86| git history lost during migration | Use `git filter-repo --to-subdirectory-filter` before merging — never move files manually |87| Remote cache not working in CI | Check TURBO_TOKEN and TURBO_TEAM env vars; verify with `turbo run build --summarize` |88| 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 |8990---9192## Best Practices93941. **Root CLAUDE.md defines the map** — document every package, its purpose, and dependency rules952. **Per-package CLAUDE.md defines the rules** — what's allowed, what's forbidden, testing commands963. **Always scope commands with --filter** — running everything on every change defeats the purpose974. **Remote cache is not optional** — without it, monorepo CI is slower than multi-repo CI985. **Changesets over manual versioning** — never hand-edit package.json versions in a monorepo996. **Shared configs in root, extended in packages** — tsconfig.base.json, .eslintrc.base.js, jest.base.config.js1007. **Impact analysis before merging shared package changes** — run affected check, communicate blast radius1018. **Keep packages/types as pure TypeScript** — no runtime code, no dependencies, fast to build and type-check102103> **Creator:** Engineering104> **License:** MIT105> **Source Repo:** `neekware/dojo-skills`106> **Source Bucket:** `engineering`107> **Original Path:** `engineering/monorepo-navigator`
neekware