Monorepo 项目规范

适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。

适用场景

• - 新建或调整 Monorepo 结构
• 管理多包依赖与任务
• 配置 Turborepo / Nx 任务编排
• 包发布与版本管理

工具选择

目录结构

pnpm + Turborepo

├── package.json # 根 package，workspace 配置
├── pnpm-workspace.yaml # workspace 包列表
├── turbo.json # Turborepo 配置
│
├── apps/
│ ├── web/ # 主应用
│ │ ├── package.json
│ │ └── ...
│ ├── admin/ # 管理后台
│ └── docs/ # 文档站
│
├── packages/
│ ├── ui/ # 共享 UI 组件
│ │ ├── package.json
│ │ └── src/
│ ├── utils/ # 工具函数
│ ├── config-eslint/ # 共享 ESLint 配置
│ └── config-typescript/ # 共享 TS 配置
│
└── tooling/ # 构建/测试工具（可选）
└── scripts/

pnpm-workspace.yaml

yaml
packages:
- apps/*
- packages/*

依赖管理

• - 内部包使用 workspace:* 协议
• 根 package.json 统一部分依赖版本，子包可覆盖
• 禁止循环依赖，通过 pnpm why 检查

json
{
dependencies: {
@repo/ui: workspace:*,
@repo/utils: workspace:*
}
}

Turborepo 任务编排

json
{
$schema: https://turbo.build/schema.json,
tasks: {
build: {
dependsOn: [^build],
outputs: [dist/, .next/]
},
lint: {
dependsOn: [^build]
},
test: {
dependsOn: [^build]
}
}
}

• - ^build 表示先执行依赖包的 build
• outputs 用于缓存命中判断

Nx 任务编排

json
{
targetDefaults: {
build: {
dependsOn: [^build],
outputs: [{projectRoot}/dist],
cache: true
}
}
}

包命名

• - 内部包：@org/package-name 或 @repo/package-name
• 发布到 npm：遵循 @scope/name 规范

强约束

• - 子包之间通过 workspace: 引用，不发布到 npm 再安装
• 共享配置（ESLint、TS）放在 packages/config-，子包 extends
• 构建顺序由依赖图决定，不手动指定无关依赖
• 根目录执行 pnpm -r build 或 turbo run build 时，所有包按序构建