monorepo-navigator

SKILL.md

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