monorepo

Monorepo Skill — 单仓多包工程

何时使用

• 多个相关项目（前端 + 后端 + 共享库 + CLI）想统一管理
• Polyrepo 已有但跨仓改动协调成本高
• 想做 atomic commit 跨包改动
• 评估 Turborepo / Nx / Bazel 选型
• 优化 CI 时间（只跑受影响的包）

一、何时该用 Monorepo / 何时不该

适合

• ✅ 共享 type 定义 / SDK / config
• ✅ 跨包重构频繁（API + Frontend 一起改）
• ✅ 团队规模 ≤ 100 人（再大需要更复杂工具如 Bazel）
• ✅ 想单一 source of truth + atomic commit

不适合

• ❌ 完全独立的产品线（共享 < 10%）
• ❌ 不同语言混合且无统一构建（Bazel 例外）
• ❌ 需要不同访问权限（开源 vs 内部代码混合 → 用 polyrepo）
• ❌ 团队没有专人维护构建系统

二、JS / TS 生态选型

工具	角色	适合
pnpm workspaces	包管理器	任何规模，性能最好（硬链接 + 严格依赖）
npm/yarn workspaces	包管理器	简单场景
Turborepo	任务编排 + 缓存	中型 / Vercel 系 / 配置简单
Nx	任务编排 + generator + plugin	大型 / 需要代码生成 / Angular 友好
Rush (Microsoft)	大型 monorepo 治理	超大型
Bazel (Google)	多语言通用构建	跨语言 / 极大型 / 接受陡峭学习
Lerna	老牌（已被 Nx 收购）	维护中，不推荐新项目

推荐组合（中型 TS 项目）：pnpm workspaces + Turborepo + Changesets。

三、pnpm workspace 标准布局

my-monorepo/
├── package.json                  # 根：私有，仅放工具依赖
├── pnpm-workspace.yaml
├── tsconfig.base.json            # 共享 TS 基础配置
├── turbo.json
├── .changeset/
│   └── config.json
├── apps/
│   ├── web/                      # Next.js 前端
│   ├── api/                      # Node.js 后端
│   └── docs/                     # 文档站
├── packages/
│   ├── ui/                       # 共享组件
│   ├── eslint-config/
│   ├── tsconfig/                 # 共享 tsconfig presets
│   ├── types/                    # 共享 type 定义
│   └── utils/
└── tools/
    └── scripts/                  # 私有脚本

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"
  - "tools/*"

// 根 package.json
{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo build",
    "dev":   "turbo dev",
    "lint":  "turbo lint",
    "test":  "turbo test",
    "changeset": "changeset",
    "release": "changeset version && pnpm install && changeset publish"
  },
  "devDependencies": {
    "turbo": "^2.0.0",
    "@changesets/cli": "^2.27.0",
    "typescript": "^5.5.0"
  }
}