monorepo-navigator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Monorepo Navigator

Monorepo导航器

Tier: POWERFUL
Category: Engineering
Domain: Monorepo Architecture / Build Systems

层级：强大级
类别：工程领域
领域：Monorepo架构 / 构建系统

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.

用于导航、管理和优化Monorepo。支持Turborepo、Nx、pnpm workspaces和Lerna。可实现跨包影响分析、仅对受影响包执行选择性构建/测试、远程缓存、依赖图谱可视化，以及从多仓库到Monorepo的结构化迁移。包含针对工作区感知开发的Claude Code配置。

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

跨包影响分析 — 当共享包发生变更时，确定哪些应用会受到影响
选择性命令 — 仅对受影响包运行测试/构建（而非全部）
依赖图谱 — 将包关系可视化为Mermaid图表
构建优化 — 远程缓存、增量构建、并行执行
迁移支持 — 分步实现从多仓库到Monorepo的迁移，且无历史记录丢失
发布管理 — 基于Changesets的版本控制、预发布渠道、npm发布流程
Claude Code配置 — 感知工作区的CLAUDE.md，包含每个包的专属说明

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

适用情况：

多个包/应用共享代码（UI组件、工具函数、类型定义、API客户端）
构建时间过长，因为任何变更都会触发全量构建
从多仓库迁移至单一仓库
需要以协同版本控制的方式将包发布至npm
团队跨多个包协作，需要统一的工具链

无需使用情况：

无共享包的单应用项目
团队/项目边界完全隔离（多仓库架构已足够）
共享代码极少，复制粘贴的成本在可接受范围内

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	JS/TS Monorepo、简单流水线配置	业界领先的远程缓存、极简配置
Nx	大型企业、插件生态系统	项目图谱、代码生成、受影响命令
pnpm workspaces	工作区协议、磁盘高效性	使用 `workspace:*` 引用本地包
Lerna	npm发布、版本控制	批量发布、约定式提交
Changesets	现代版本控制（优先于Lerna）	变更日志生成、预发布渠道

现代主流组合：pnpm workspaces + Turborepo + Changesets

Turborepo

→ See references/monorepo-tooling-reference.md for details

→ 详情请参阅 references/monorepo-tooling-reference.md

Workspace Analyzer

工作区分析器

bash

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.

bash

python3 scripts/monorepo_analyzer.py /path/to/monorepo
python3 scripts/monorepo_analyzer.py /path/to/monorepo --json

另可参阅

references/monorepo-patterns.md

了解常见架构和CI模式。

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

常见问题	解决方案
每次PR都运行不带 `--filter` 的 `turbo run build`	在CI中始终使用 `--filter=...[origin/main]`
`workspace:*` 引用导致发布失败	使用 `pnpm changeset publish` — 它会自动将 `workspace:*` 替换为实际版本
无关文件变更触发全量包构建	调整turbo.json中的 `inputs` ，将文档、配置文件排除在缓存键之外
共享tsconfig导致单个包故障影响所有类型检查	正确使用 `extends` — 每个包继承根配置，但覆盖 `rootDir` / `outDir`
迁移过程中丢失git历史记录	合并前使用 `git filter-repo --to-subdirectory-filter` — 切勿手动移动文件
CI中远程缓存无法工作	检查TURBO_TOKEN和TURBO_TEAM环境变量；使用 `turbo run build --summarize` 验证
CLAUDE.md过于通用 — Claude修改了错误的包	在每个包的CLAUDE.md中添加明确规则，例如"处理X时，仅修改apps/X中的文件"

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

根目录CLAUDE.md定义全局映射 — 记录每个包的用途和依赖规则
每个包的CLAUDE.md定义专属规则 — 允许/禁止操作、测试命令
始终用--filter限定命令范围 — 每次变更都全量执行违背Monorepo的初衷
远程缓存必不可少 — 若无远程缓存，Monorepo的CI速度会慢于多仓库架构
优先使用Changesets而非手动版本控制 — 切勿在Monorepo中手动编辑package.json的版本号
共享配置放在根目录，包中继承扩展 — 例如tsconfig.base.json、.eslintrc.base.js、jest.base.config.js
合并共享包变更前先做影响分析 — 运行受影响检查，告知影响范围
保持类型包为纯TypeScript — 无运行时代码、无依赖，构建和类型检查速度更快