monorepo-navigator（单一存储库导航器）

Monorepo Navigator

Tier: POWERFUL Category: Engineering / Build Systems Maintainer: Claude Skills Team

Overview

Navigate, manage, and optimize monorepos at any scale. Covers Turborepo, Nx, pnpm workspaces, and Lerna/Changesets for cross-package impact analysis, selective builds on affected packages only, dependency graph visualization, remote caching configuration, migration from multi-repo to monorepo with preserved git history, and coordinated package publishing with automated changelogs.

Keywords

monorepo, Turborepo, Nx, pnpm workspaces, Changesets, dependency graph, remote cache, affected packages, selective builds, cross-package impact, npm publishing, workspace protocol

Core Capabilities

1. Impact Analysis

• Determine which apps break when a shared package changes
• Trace dependency chains from leaf packages to root apps
• Visualize impact as Mermaid dependency graphs
• Calculate blast radius for any file change

2. Selective Execution

• Run tests/builds only for affected packages (not everything)
• Filter by changed files since a git ref
• Scope commands to specific packages and their dependents
• Skip unchanged packages in CI for faster feedback

3. Build Optimization

• Remote caching with Turborepo (Vercel) or Nx Cloud
• Incremental builds with proper input/output configuration
• Parallel execution with dependency-aware scheduling
• Artifact sharing between CI jobs

4. Publishing

• Changesets for coordinated versioning across packages
• Automated changelog generation per package
• Pre-release channels (alpha, beta, rc)
• workspace:* protocol replacement during publish

When to Use

• Multiple packages/apps share code (UI components, utils, types, API clients)
• Build times are slow because everything rebuilds on every change
• Migrating from multiple repos to a single monorepo
• Publishing npm packages with coordinated versioning
• Teams work across packages and need unified tooling

Tool Selection Decision Matrix

Recommended modern stack: pnpm workspaces + Turborepo + Changesets

Monorepo Structure

my-monorepo/
├── apps/
│   ├── web/                    # Next.js frontend
│   │   ├── package.json        # depends on @repo/ui, @repo/utils
│   │   └── ...
│   ├── api/                    # Express/Fastify backend
│   │   ├── package.json        # depends on @repo/db, @repo/utils
│   │   └── ...
│   └── mobile/                 # React Native app
│       ├── package.json
│       └── ...
├── packages/
│   ├── ui/                     # Shared React components
│   │   ├── package.json        # @repo/ui
│   │   └── ...
│   ├── utils/                  # Shared utilities
│   │   ├── package.json        # @repo/utils
│   │   └── ...
│   ├── db/                     # Database client + schema
│   │   ├── package.json        # @repo/db
│   │   └── ...
│   ├── types/                  # Shared TypeScript types
│   │   ├── package.json        # @repo/types (no runtime deps)
│   │   └── ...
│   └── config/                 # Shared configs (tsconfig, eslint)
│       ├── tsconfig.base.json
│       └── eslint.base.js
├── turbo.json                  # Turborepo pipeline config
├── pnpm-workspace.yaml         # Workspace package locations
├── package.json                # Root scripts, devDependencies
└── .changeset/                 # Changeset config
    └── config.json

Turborepo Configuration

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV", "CI"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json", "package.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_*"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tests/**", "vitest.config.*"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", ".eslintrc.*", "tsconfig.json"]
    },
    "typecheck": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Key Turborepo Commands

# Run all tasks
turbo run build

# Run only affected packages (compared to main)
turbo run build test --filter='...[origin/main]'

# Run for a specific package and its dependencies
turbo run build --filter=@repo/web...

# Run for a specific package only (no deps)
turbo run test --filter=@repo/ui

# Dry run to see what would execute
turbo run build --dry=json

# View dependency graph
turbo run build --graph=graph.html

# Summarize cache usage
turbo run build --summarize

pnpm Workspace Configuration

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

Cross-Package References

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "main": "./src/index.ts",
  "types": "./src/index.ts",
  "dependencies": {
    "@repo/types": "workspace:*"
  }
}

// apps/web/package.json
{
  "name": "@repo/web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "@repo/utils": "workspace:*"
  }
}

Workspace Commands

# Install all workspace dependencies
pnpm install

# Add a dependency to a specific package
pnpm add zod --filter @repo/api

# Add a workspace package as dependency
pnpm add @repo/utils --filter @repo/web --workspace

# Run a script in a specific package
pnpm --filter @repo/web dev

# Run a script in all packages that have it
pnpm -r run build

# List all packages
pnpm -r ls --depth -1

Impact Analysis

Find All Dependents of a Changed Package

# Using turbo to see what depends on @repo/ui
turbo run build --filter='...@repo/ui' --dry=json | \
  jq '.tasks[].package' -r | sort -u

# Manual: search for imports of a package
grep -r "from '@repo/ui'" apps/ packages/ --include="*.ts" --include="*.tsx" -l

Dependency Graph Visualization

# Generate HTML visualization
turbo run build --graph=dependency-graph.html

# Generate DOT format for custom rendering
turbo run build --graph=deps.dot

# Quick Mermaid diagram from package.json files
echo "graph TD"
for pkg in packages/*/package.json apps/*/package.json; do
  name=$(jq -r '.name' "$pkg")
  jq -r '.dependencies // {} | keys[] | select(startswith("@repo/"))' "$pkg" | while read dep; do
    echo "  $name --> $dep"
  done
done

Remote Caching

Turborepo Remote Cache (Vercel)

# Login to Vercel (one-time)
turbo login

# Link repo to Vercel team
turbo link

# CI: set environment variables
# TURBO_TOKEN=<vercel-token>
# TURBO_TEAM=<team-slug>

# Verify remote cache works
turbo run build --summarize
# Look for "Remote cache: hit" entries

Self-Hosted Remote Cache

# Using ducktape/turborepo-remote-cache
docker run -p 3000:3000 \
  -e STORAGE_PROVIDER=local \
  -e STORAGE_PATH=/cache \
  ducktape/turborepo-remote-cache

# Configure turbo to use it
# turbo.json:
# { "remoteCache": { "apiUrl": "http://cache-server:3000" } }

CI/CD with Affected Packages Only

# .github/workflows/ci.yml
name: CI
on:
  pull_request:

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # needed for --filter comparisons

      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # Only lint/test/build affected packages
      - run: turbo run lint test build --filter='...[origin/main]'
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Publishing with Changesets

Setup

# Install changesets
pnpm add -D -w @changesets/cli @changesets/changelog-github

# Initialize
pnpm changeset init

.changeset/config.json

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": ["@changesets/changelog-github", { "repo": "org/repo" }],
  "commit": false,
  "fixed": [],
  "linked": [["@repo/ui", "@repo/utils"]],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}

Publishing Workflow

# 1. Developer adds a changeset for their changes
pnpm changeset
# Interactive: select packages, bump type (patch/minor/major), summary

# 2. Before release: consume changesets and bump versions
pnpm changeset version
# Updates package.json versions and CHANGELOG.md files

# 3. Publish to npm
pnpm changeset publish
# Replaces workspace:* with real versions and publishes

Migration: Multi-Repo to Monorepo

# 1. Preserve git history using filter-repo
# In each source repo:
git filter-repo --to-subdirectory-filter packages/ui
git filter-repo --to-subdirectory-filter apps/api

# 2. Create monorepo and merge histories
mkdir monorepo && cd monorepo && git init
git remote add ui ../old-ui-repo
git fetch ui --no-tags
git merge ui/main --allow-unrelated-histories

git remote add api ../old-api-repo
git fetch api --no-tags
git merge api/main --allow-unrelated-histories

# 3. Set up workspace configuration
# Add pnpm-workspace.yaml, turbo.json, root package.json

# 4. Update internal imports
# Change "ui-package" imports to "@repo/ui"
# Change npm versions to "workspace:*"

# 5. Verify
pnpm install
turbo run build test

Common Pitfalls

Best Practices

1. Root package.json has no runtime dependencies — only devDependencies and scripts
2. Always scope commands with --filter in CI — running everything defeats the monorepo purpose
3. Remote cache is not optional — without it, monorepo CI is slower than multi-repo
4. Shared configs extend from root — tsconfig.base.json, eslint.base.js, vitest shared config
5. packages/types is pure TypeScript — no runtime code, no dependencies, fastest to build
6. Changesets over manual versioning — never hand-edit package.json versions in a monorepo
7. Impact analysis before merging shared package changes — check affected packages, communicate blast radius
8. **Keep workspace:* for internal deps** — real version ranges are for external npm packages only

Troubleshooting

Success Criteria

• Build time reduction: CI pipeline completes affected-only builds in under 50% of full-build time within 2 weeks of adoption
• Cache hit rate: Remote cache achieves 70%+ hit rate on PR builds after initial warm-up period
• Impact visibility: Every PR includes an affected-packages summary showing blast radius of changes
• Zero full rebuilds in CI: No CI workflow runs all packages unconditionally; every pipeline uses --filter or equivalent
• Publishing reliability: Changesets workflow produces correct versions and changelogs with zero manual package.json edits per release cycle
• Migration completeness: Multi-repo to monorepo migration preserves 100% of git history for all migrated packages
• Developer onboarding: New team members can run, build, and test any package locally within 15 minutes using documented workspace commands

Scope & Limitations

This skill covers:

• Turborepo, Nx, and pnpm workspace configuration and optimization
• Cross-package dependency analysis and impact visualization
• Remote caching setup (Vercel, Nx Cloud, self-hosted)
• Changesets-based coordinated versioning and npm publishing

This skill does NOT cover:

• Application-level build configuration (webpack, Vite, esbuild internals) — see performance-profiler
• CI/CD pipeline design beyond monorepo-specific filters — see ci-cd-pipeline-builder
• Git branching strategies and release flow — see release-manager
• Dependency vulnerability scanning and license auditing — see dependency-auditor

Integration Points