monorepo-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

激活本技能后，你的第一条回复请始终以🧢表情开头。

Monorepo Management

Monorepo管理

A monorepo is a single version-controlled repository that houses multiple packages or applications sharing common tooling, dependencies, and build infrastructure. Done well, a monorepo eliminates dependency drift between packages, enables atomic cross-package changes, and lets you run only the builds and tests affected by a given change. This skill covers workspace managers (pnpm, npm, yarn), task orchestrators (Turborepo, Nx), enterprise build systems (Bazel), internal package patterns, and shared tooling config.

Monorepo是一个单一的版本控制仓库，用于存放多个共享通用工具、依赖和构建基础设施的包或应用。管理得当的Monorepo可以消除包之间的依赖漂移，支持跨包原子变更，并且只运行给定变更所影响的构建和测试任务。本技能涵盖工作区管理器（pnpm、npm、yarn）、任务编排器（Turborepo、Nx）、企业级构建系统（Bazel）、内部包模式以及共享工具配置。

When to use this skill

何时使用本技能

Trigger this skill when the user:

Wants to set up a new monorepo or migrate from a multi-repo setup
Asks how to configure Turborepo pipelines, caching, or remote caching
Asks how to use Nx projects, affected commands, or the Nx task graph
Needs to share TypeScript, ESLint, or Prettier configs across packages
Asks about pnpm/npm/yarn workspace protocols and dependency hoisting
Wants to implement internal packages with proper bundling and type exports
Needs to choose between Turborepo, Nx, Bazel, or Lerna
Asks about build caching, cache invalidation, or remote cache setup

Do NOT trigger this skill for:

Single-package repository build tooling (Vite, webpack, esbuild) - use the frontend or backend skill
Docker/container orchestration even when containers come from a monorepo

当用户有以下需求时，触发本技能：

想要搭建新的monorepo，或是从多仓库架构迁移到monorepo
询问如何配置Turborepo流水线、缓存或远程缓存
询问如何使用Nx项目、affected命令或Nx任务图
需要在多个包之间共享TypeScript、ESLint或Prettier配置
询问pnpm/npm/yarn工作区协议和依赖提升相关问题
想要实现带有正确打包和类型导出的内部包
需要在Turborepo、Nx、Bazel或Lerna之间做选择
询问构建缓存、缓存失效或远程缓存搭建相关问题

请勿在以下场景触发本技能：

单包仓库的构建工具（Vite、webpack、esbuild）——请使用前端或后端技能
Docker/容器编排（即使容器来自monorepo）

Key principles

核心原则

Single source of truth - Each config (TypeScript base, ESLint rules, Prettier) lives in exactly one package and is extended everywhere else. Duplication is the root cause of config drift.
Explicit dependencies - Every package declares its workspace dependencies with
```
workspace:*
```
. Never rely on hoisting to make an undeclared dependency available at runtime.
Cache everything - Every deterministic task should be cached. Define precise
```
inputs
```
and
```
outputs
```
so the cache is never stale and never over-broad. Remote caching multiplies this benefit across CI and team.
Affected-only builds - On CI, build and test only the packages that changed (directly or transitively). Running the full build on every PR does not scale past ~20 packages.
Consistent tooling - Use the same package manager, Node version, and task runner across all packages. Mixed tooling creates invisible resolution differences and breaks cache hits.

单一事实来源 - 每个配置（TypeScript基础配置、ESLint规则、Prettier）仅存于一个包中，其他所有包都从该包扩展。重复配置是导致配置漂移的根本原因。
显式依赖 - 每个包都使用
```
workspace:*
```
声明其工作区依赖。永远不要依赖依赖提升来让未声明的依赖在运行时可用。
缓存一切 - 每个确定性任务都应该被缓存。定义精确的
```
inputs
```
和
```
outputs
```
，确保缓存不会过期或范围过宽。远程缓存可以在CI和团队成员之间放大这一优势。
仅构建受影响的内容 - 在CI中，仅构建和测试发生变更的包（直接或间接影响的）。每次PR都运行完整构建在包数量超过20个后将无法扩展。
一致的工具链 - 在所有包中使用相同的包管理器、Node版本和任务运行器。混合工具链会导致不可见的依赖解析差异，并破坏缓存命中。

Core concepts

核心概念

Workspace protocols

工作区协议

Protocol	Package manager	Meaning
`workspace:*`	pnpm	Any version from workspace, keep `*` in lockfile
`workspace:^`	pnpm	Resolve range but pin a semver range
`*`	yarn berry	Any version, resolved from workspace
`file:../pkg`	npm	Path reference (no lockfile version management)

协议	包管理器	含义
`workspace:*`	pnpm	使用工作区内的任意版本，在锁文件中保留 `*`
`workspace:^`	pnpm	解析版本范围，但固定为语义化版本范围
`*`	yarn berry	任意版本，从工作区中解析
`file:../pkg`	npm	路径引用（无锁文件版本管理）

Task graph

任务图

Turborepo and Nx model tasks as a DAG. A

build

task with

dependsOn: ["^build"]

means all dependency packages must complete their build before the current package starts. This replaces manual ordering scripts.

Turborepo和Nx将任务建模为有向无环图（DAG）。带有

dependsOn: ["^build"]

的

build

任务意味着所有依赖包必须先完成自身的构建，当前包才能开始构建。这替代了手动排序的脚本。

Remote caching

远程缓存

Remote caches (Vercel, Nx Cloud, S3/GCS) store task outputs keyed by a hash of inputs. Any machine with the same inputs gets a cache hit and downloads outputs instead of recomputing. This can reduce CI time by 80-90%.

远程缓存（Vercel、Nx Cloud、S3/GCS）通过输入内容的哈希值来存储任务输出。任何拥有相同输入的机器都能命中缓存，直接下载输出而非重新计算。这可以将CI时间减少80-90%。

Affected analysis

受影响分析

Given a diff from a base branch, affected analysis walks the dependency graph in reverse to find every package that transitively depends on a changed package. Turborepo:

--filter=...[HEAD^1]

. Nx:

nx affected -t build

基于与基准分支的差异，受影响分析会反向遍历依赖图，找出所有被变更包直接或间接影响的包。Turborepo命令：

--filter=...[HEAD^1]

。Nx命令：

nx affected -t build

。

Dependency topology

依赖拓扑

Packages form a partial order: leaf packages (utils, tokens) have no internal deps; feature packages depend on leaves; apps depend on features. Circular dependencies break the DAG and must be detected early.

包形成一个偏序结构：叶子包（工具类、令牌类）没有内部依赖；功能包依赖叶子包；应用依赖功能包。循环依赖会破坏DAG结构，必须尽早检测。

Common tasks

常见任务

1. Set up pnpm workspaces

1. 搭建pnpm工作区

pnpm-workspace.yaml
:

yaml

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

Root
package.json
:

json

{
  "name": "my-monorepo",
  "private": true,
  "packageManager": "pnpm@9.4.0",
  "engines": { "node": ">=20.0.0", "pnpm": ">=9.0.0" },
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev --parallel",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": { "turbo": "^2.0.0" }
}

Referencing an internal package:

json

{ "dependencies": { "@myorg/tokens": "workspace:*" } }

pnpm-workspace.yaml
:

yaml

packages:
  - "apps/*"
  - "packages/*"
  - "tooling/*"

根目录
package.json
:

json

{
  "name": "my-monorepo",
  "private": true,
  "packageManager": "pnpm@9.4.0",
  "engines": { "node": ">=20.0.0", "pnpm": ">=9.0.0" },
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev --parallel",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": { "turbo": "^2.0.0" }
}

引用内部包:

json

{ "dependencies": { "@myorg/tokens": "workspace:*" } }

2. Configure Turborepo

2. 配置Turborepo

turbo.json
:

json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json", "package.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "typecheck": { "dependsOn": ["^build"], "inputs": ["src/**", "tsconfig.json"] },
    "lint":      { "inputs": ["src/**", "eslint.config.js"] },
    "test":      { "dependsOn": ["^build"], "inputs": ["src/**", "tests/**"], "outputs": ["coverage/**"] },
    "dev":       { "cache": false, "persistent": true }
  }
}

Environment variable inputs (invalidate cache on env change):

json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["NODE_ENV", "NEXT_PUBLIC_API_URL"],
      "outputs": ["dist/**"]
    }
  }
}

Remote caching (Vercel) + affected CI runs:

bash

npx turbo login && npx turbo link          # set up once
turbo run build --filter=...[origin/main]  # CI affected builds

turbo.json
:

json

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tsconfig.json", "package.json"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "typecheck": { "dependsOn": ["^build"], "inputs": ["src/**", "tsconfig.json"] },
    "lint":      { "inputs": ["src/**", "eslint.config.js"] },
    "test":      { "dependsOn": ["^build"], "inputs": ["src/**", "tests/**"], "outputs": ["coverage/**"] },
    "dev":       { "cache": false, "persistent": true }
  }
}

环境变量输入（环境变更时失效缓存）:

json

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["NODE_ENV", "NEXT_PUBLIC_API_URL"],
      "outputs": ["dist/**"]
    }
  }
}

远程缓存（Vercel）+ CI中仅构建受影响内容:

bash

npx turbo login && npx turbo link          # 一次性配置
turbo run build --filter=...[origin/main]  # CI中仅构建受影响内容

3. Configure Nx

3. 配置Nx

nx.json
:

json

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "defaultBase": "main",
  "namedInputs": {
    "default":    ["{projectRoot}/**/*", "sharedGlobals"],
    "production": ["default", "!{projectRoot}/**/*.spec.*"],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": { "dependsOn": ["^build"], "inputs": ["production", "^production"], "cache": true },
    "test":  { "inputs": ["default", "^production"], "cache": true },
    "lint":  { "inputs": ["default"], "cache": true }
  },
  "nxCloudAccessToken": "YOUR_NX_CLOUD_TOKEN"
}

Affected commands:

bash

nx show projects --affected --base=main   # show affected projects
nx affected -t build                      # build only affected
nx affected -t test --parallel=4          # test in parallel
nx graph                                  # visualize dependency graph

nx.json
:

json

{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "defaultBase": "main",
  "namedInputs": {
    "default":    ["{projectRoot}/**/*", "sharedGlobals"],
    "production": ["default", "!{projectRoot}/**/*.spec.*"],
    "sharedGlobals": ["{workspaceRoot}/tsconfig.base.json"]
  },
  "targetDefaults": {
    "build": { "dependsOn": ["^build"], "inputs": ["production", "^production"], "cache": true },
    "test":  { "inputs": ["default", "^production"], "cache": true },
    "lint":  { "inputs": ["default"], "cache": true }
  },
  "nxCloudAccessToken": "YOUR_NX_CLOUD_TOKEN"
}

受影响命令:

bash

nx show projects --affected --base=main   # 显示受影响的项目
nx affected -t build                      # 仅构建受影响的项目
nx affected -t test --parallel=4          # 并行测试
nx graph                                  # 可视化依赖图

4. Share TypeScript configs across packages

4. 在多个包之间共享TypeScript配置

tooling/tsconfig/base.json
:

json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

Individual package
tsconfig.json
:

json

{
  "extends": "@myorg/tsconfig/base.json",
  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
  "include": ["src"],
  "exclude": ["dist", "node_modules"]
}

tooling/tsconfig/base.json
:

json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true,
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

单个包的
tsconfig.json
:

json

{
  "extends": "@myorg/tsconfig/base.json",
  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
  "include": ["src"],
  "exclude": ["dist", "node_modules"]
}

5. Set up shared ESLint/Prettier configs

5. 搭建共享ESLint/Prettier配置

tooling/eslint-config/index.js
(flat config, ESLint 9+):

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettierConfig from "eslint-config-prettier";

export const base = [
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  prettierConfig,
  {
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "@typescript-eslint/consistent-type-imports": "error",
    },
  },
];

tooling/prettier-config/index.js
:

/** @type {import("prettier").Config} */
export default { semi: true, singleQuote: false, trailingComma: "all", printWidth: 100 };

tooling/eslint-config/index.js
（扁平配置，ESLint 9+）:

import js from "@eslint/js";
import tseslint from "typescript-eslint";
import prettierConfig from "eslint-config-prettier";

export const base = [
  js.configs.recommended,
  ...tseslint.configs.recommendedTypeChecked,
  prettierConfig,
  {
    rules: {
      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
      "@typescript-eslint/consistent-type-imports": "error",
    },
  },
];

tooling/prettier-config/index.js
:

/** @type {import("prettier").Config} */
export default { semi: true, singleQuote: false, trailingComma: "all", printWidth: 100 };

6. Implement internal packages (tsup)

6. 实现内部包（使用tsup）

packages/utils/package.json
:

json

{
  "name": "@myorg/utils",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" }
  },
  "scripts": { "build": "tsup", "dev": "tsup --watch" },
  "devDependencies": { "tsup": "^8.0.0" }
}

tsup.config.ts
:

import { defineConfig } from "tsup";
export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,
  sourcemap: true,
  clean: true,
});

For packages consumed only within the repo (no publish), skip the build step entirely and use TypeScript path aliases in

tsconfig.base.json

json

{ "compilerOptions": { "paths": { "@myorg/utils": ["packages/utils/src/index.ts"] } } }

packages/utils/package.json
:

json

{
  "name": "@myorg/utils",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "exports": {
    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" }
  },
  "scripts": { "build": "tsup", "dev": "tsup --watch" },
  "devDependencies": { "tsup": "^8.0.0" }
}

tsup.config.ts
:

import { defineConfig } from "tsup";
export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],
  dts: true,
  sourcemap: true,
  clean: true,
});

对于仅在仓库内部使用的包（无需发布），可以完全跳过构建步骤，在

tsconfig.base.json

中使用TypeScript路径别名：

json

{ "compilerOptions": { "paths": { "@myorg/utils": ["packages/utils/src/index.ts"] } } }

7. Choose Turborepo vs Nx vs Bazel

7. 选择Turborepo vs Nx vs Bazel

See

references/tool-comparison.md

for the full feature matrix.

Team / project profile	Recommended tool
JS/TS monorepo, small-medium team, fast setup	Turborepo
JS/TS monorepo, want generators + boundary enforcement	Nx
Polyglot repo (Go, Java, Python + JS), 100+ packages	Bazel
Already on Nx Cloud, need distributed task execution	Nx
Migrating from Lerna	Turborepo (drop-in) or Nx (migration tooling)

Quick rule: Start with Turborepo. Upgrade to Nx when you need project generators,

@nx/enforce-module-boundaries

, or Nx Cloud DTE. Only adopt Bazel for a genuinely polyglot repo with build engineering capacity.

完整的功能对比请参考

references/tool-comparison.md

。

团队/项目概况	推荐工具
JS/TS monorepo、中小型团队、快速搭建	Turborepo
JS/TS monorepo、需要生成器 + 边界约束	Nx
多语言仓库（Go、Java、Python + JS）、100+个包	Bazel
已使用Nx Cloud、需要分布式任务执行	Nx
从Lerna迁移	Turborepo（无缝替换）或Nx（有迁移工具）

快速规则：从Turborepo开始。当你需要项目生成器、

@nx/enforce-module-boundaries

或Nx Cloud分布式任务执行时，升级到Nx。只有当你真正拥有多语言仓库且有构建工程能力时，才考虑使用Bazel。

Anti-patterns / common mistakes

反模式/常见错误

Anti-pattern	Problem	Fix
Relying on hoisted node_modules for unlisted deps	Breaks when hoisting changes; silent cross-package contamination	Declare every dep in the package that uses it
`"outputs": ["**"]` in turbo.json	Caches node_modules, inflates cache size, poisons hits	List only build artifacts: `dist/` , `.next/`
Missing `"dependsOn": ["^build"]` on build task	Downstream packages build before deps are ready; missing types/files	Always set `^build` dependsOn for build tasks
Circular workspace dependencies	Breaks the task DAG; tools silently skip or hang	Use `nx graph` or `madge` to detect; enforce via lint
Publishing internal packages to npm to share within the repo	Introduces a publish cycle where `workspace:*` suffices	Use workspace protocol; only publish genuinely public packages

反模式	问题	修复方案
依赖提升的node_modules来获取未声明的依赖	当依赖提升规则变化时会失效；导致包之间的隐性污染	在使用依赖的包中声明所有依赖
turbo.json中设置 `"outputs": ["**"]`	缓存node_modules，增大缓存体积，破坏缓存命中	仅列出构建产物： `dist/` , `.next/`
build任务缺少 `"dependsOn": ["^build"]`	下游包在依赖包构建完成前就开始构建；缺少类型/文件	始终为build任务设置 `^build` 依赖
工作区循环依赖	破坏任务DAG；工具会静默跳过或挂起	使用 `nx graph` 或 `madge` 检测；通过lint规则强制避免
将内部包发布到npm以在仓库内部共享	引入不必要的发布流程，而 `workspace:*` 即可满足需求	使用工作区协议；仅发布真正公开的包

References

参考资料

Turborepo docs
Nx docs
Bazel docs
pnpm workspaces
tsup
changesets - versioning/publishing (Lerna replacement)
```
references/tool-comparison.md
```
- detailed Turborepo vs Nx vs Bazel vs Lerna comparison

Turborepo文档
Nx文档
Bazel文档
pnpm workspaces
tsup
changesets - 版本管理/发布工具（Lerna替代方案）
```
references/tool-comparison.md
```
- Turborepo、Nx、Bazel、Lerna的详细对比

monorepo-management

Original

Translation

Monorepo Management

Monorepo管理

When to use this skill

何时使用本技能

Key principles

核心原则

Core concepts

核心概念

Workspace protocols

工作区协议

Task graph

任务图

Remote caching

远程缓存

Affected analysis

受影响分析

Dependency topology

依赖拓扑

Common tasks

常见任务

1. Set up pnpm workspaces

1. 搭建pnpm工作区

2. Configure Turborepo

2. 配置Turborepo

3. Configure Nx

3. 配置Nx

4. Share TypeScript configs across packages

4. 在多个包之间共享TypeScript配置

5. Set up shared ESLint/Prettier configs

5. 搭建共享ESLint/Prettier配置

6. Implement internal packages (tsup)

6. 实现内部包（使用tsup）

7. Choose Turborepo vs Nx vs Bazel

7. 选择Turborepo vs Nx vs Bazel

Anti-patterns / common mistakes

反模式/常见错误

References

参考资料

Related skills

相关技能