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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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]
