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.
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.
zh_description
用于Monorepo、导航，支持开发、调试、评审和交付。
version
1.0.0
author
seaworld008
source
in-house
source_url
tags
["development", "monorepo", "navigator"]
created_at
2026-03-04
updated_at
2026-03-20
quality
5
complexity
intermediate
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
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
turbo.json pipeline config
{"$schema":"https://turbo.build/schema.json","globalEnv":["NODE_ENV","DATABASE_URL"],"pipeline":{"build":{"dependsOn":["^build"],// build deps first (topological order)"outputs":[".next/**","dist/**","build/**"],"env":["NEXT_PUBLIC_API_URL"]},"test":{"dependsOn":["^build"],// need built deps to test"outputs":["coverage/**"],"cache":true},"lint":{"outputs":[],"cache":true},"dev":{"cache":false,// never cache dev servers"persistent":true// long-running process},"type-check":{"dependsOn":["^build"],"outputs":[]}}}
Key commands
# Build everything (respects dependency order)
turbo run build
# Build only affected packages (requires --filter)
turbo run build --filter=...[HEAD^1] # changed since last commit
turbo run build --filter=...[main] # changed vs main branch# Test only affected
turbo run test --filter=...[HEAD^1]
# Run for a specific app and all its dependencies
turbo run build --filter=@myorg/web...
# Run for a specific package only (no dependencies)
turbo run build --filter=@myorg/ui
# Dry-run — see what would run without executing
turbo run build --dry-run
# Enable remote caching (Vercel Remote Cache)
turbo login
turbo link
Remote caching setup
# .turbo/config.json (auto-created by turbo link)
{
"teamid": "team_xxxx",
"apiurl": "https://vercel.com"
}
# Self-hosted cache server (open-source alternative)# Run ducktape/turborepo-remote-cache or Turborepo's official server
TURBO_API=http://your-cache-server.internal \
TURBO_TOKEN=your-token \
TURBO_TEAM=your-team \
turbo run build
Nx
Project graph and affected commands
# Install
npx create-nx-workspace@latest my-monorepo
# Visualize the project graph (opens browser)
nx graph
# Show affected packages for the current branch
nx affected:graph
# Run only affected tests
nx affected --target=test# Run only affected builds
nx affected --target=build
# Run affected with base/head (for CI)
nx affected --target=test --base=main --head=HEAD
// apps/web/package.json{"name":"@myorg/web","dependencies":{"@myorg/ui":"workspace:*",// always use local version"@myorg/utils":"workspace:^",// local, but respect semver on publish"@myorg/types":"workspace:~"}}
Useful pnpm workspace commands
# Install all packages across workspace
pnpm install
# Run script in a specific package
pnpm --filter @myorg/web dev
# Run script in all packages
pnpm --filter "*" build
# Run script in a package and all its dependencies
pnpm --filter @myorg/web... build
# Add a dependency to a specific package
pnpm --filter @myorg/web add react
# Add a shared dev dependency to root
pnpm add -D typescript -w
# List workspace packages
pnpm ls --depth -1 -r
Cross-Package Impact Analysis
When a shared package changes, determine what's affected before you ship.
# Using Turborepo — show affected packages
turbo run build --filter=...[HEAD^1] --dry-run 2>&1 | grep "Tasks to run"# Using Nx
nx affected:apps --base=main --head=HEAD # which apps are affected
nx affected:libs --base=main --head=HEAD # which libs are affected# Manual analysis with pnpm# Find all packages that depend on @myorg/utils:
grep -r '"@myorg/utils"' packages/*/package.json apps/*/package.json
# Using jq for structured outputfor pkg in packages/*/package.json apps/*/package.json; do
name=$(jq -r '.name'"$pkg")
if jq -e '.dependencies["@myorg/utils"] // .devDependencies["@myorg/utils"]'"$pkg" > /dev/null 2>&1; thenecho"$name depends on @myorg/utils"fidone
graph TD
web --> ui
web --> utils
web --> types
mobile --> ui
mobile --> utils
mobile --> types
admin --> ui
admin --> utils
api --> types
ui --> utils
Claude Code Configuration (Workspace-Aware CLAUDE.md)
Place a root CLAUDE.md + per-package CLAUDE.md files:
# /CLAUDE.md — Root (applies to all packages)## Monorepo Structure- apps/web — Next.js customer-facing app
- apps/admin — Next.js internal admin
- apps/api — Express REST API
- packages/ui — Shared React component library
- packages/utils — Shared utilities (pure functions only)
- packages/types — Shared TypeScript types (no runtime code)
## Build System- pnpm workspaces + Turborepo
- Always use `pnpm --filter <package>` to scope commands
- Never run `npm install` or `yarn` — pnpm only
- Run `turbo run build --filter=...[HEAD^1]` before committing
## Task Scoping Rules- When modifying packages/ui: also run tests for apps/web and apps/admin (they depend on it)
- When modifying packages/types: run type-check across ALL packages
- When modifying apps/api: only need to test apps/api
## Package Manager
pnpm — version pinned in packageManager field of root package.json
# /packages/ui/CLAUDE.md — Package-specific## This Package
Shared React component library. Zero business logic. Pure UI only.
## Rules- All components must be exported from src/index.ts
- No direct API calls in components — accept data via props
- Every component needs a Storybook story in src/stories/
- Use Tailwind for styling — no CSS modules or styled-components
## Testing- Component tests: `pnpm --filter @myorg/ui test`- Visual regression: `pnpm --filter @myorg/ui test:storybook`## Publishing- Version bumps via changesets only — never edit package.json version manually
- Run `pnpm changeset` from repo root after changes
Migration: Multi-Repo → Monorepo
# Step 1: Create monorepo scaffoldmkdir my-monorepo && cd my-monorepo
pnpm init
echo"packages:\n - 'apps/*'\n - 'packages/*'" > pnpm-workspace.yaml
# Step 2: Move repos with git history preservedmkdir -p apps packages
# For each existing repo:
git clone https://github.com/myorg/web-app
cd web-app
git filter-repo --to-subdirectory-filter apps/web # rewrites history into subdircd ..
git remote add web-app ./web-app
git fetch web-app --tags
git merge web-app/main --allow-unrelated-histories
# Step 3: Update package names to scoped# In each package.json, change "name": "web" to "name": "@myorg/web"# Step 4: Replace cross-repo npm deps with workspace:*# apps/web/package.json: "@myorg/ui": "1.2.3" → "@myorg/ui": "workspace:*"# Step 5: Add shared configs to rootcp apps/web/.eslintrc.js .eslintrc.base.js
# Update each package's config to extend root:# { "extends": ["../../.eslintrc.base.js"] }# Step 6: Add Turborepo
pnpm add -D turbo -w
# Create turbo.json (see above)# Step 7: Unified CI (see CI section below)# Step 8: Test everything
turbo run build test lint
CI Patterns
GitHub Actions — Affected Only
# .github/workflows/ci.ymlname:CIon:push:branches: [main]
pull_request:jobs:affected:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4with:fetch-depth:0# full history needed for affected detection-uses:pnpm/action-setup@v3with:version:9-uses:actions/setup-node@v4with:node-version:20cache:pnpm-run:pnpminstall--frozen-lockfile# Turborepo remote cache-uses:actions/cache@v4with:path:.turbokey:${{runner.os}}-turbo-${{github.sha}}restore-keys:${{runner.os}}-turbo-# Only test/build affected packages-name:Buildaffectedrun:turborunbuild--filter=...[origin/main]env:TURBO_TOKEN:${{secrets.TURBO_TOKEN}}TURBO_TEAM:${{vars.TURBO_TEAM}}-name:Testaffectedrun:turboruntest--filter=...[origin/main]-name:Lintaffectedrun:turborunlint--filter=...[origin/main]
