monorepo-project-standard

# Monorepo 项目规范 适用于使用 pnpm workspace、Turborepo 或 Nx 的多包前端仓库。 ## 适用场景 - 新建或调整 Monorepo 结构 - 管理多包依赖与任务 - 配置 Turborepo / Nx 任务编排 - 包发布与版本管理 ## 工具选择 | 工具 | 适用 | 特点 | |------|------|------| | **pnpm workspace** | 基础 | 依赖提升、链接、脚本聚合 | | **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` 时，所有包按序构建