十条经过实战检验的 TypeScript Monorepo 最佳实践

1
apps/
2
  web/              # Web 应用
3
  worker/           # 后台任务处理
4
packages/
5
  auth/             # 认证授权模块
6
  billing/          # 计费结算模块
7
  search/           # 搜索功能模块
8
  ui/               # UI 组件库

1
// package.json (root)
2
{
3
  "name": "@acme/monorepo",
4
  "private": true,
5
  "packageManager": "pnpm@9.0.0",
6
  "workspaces": ["apps/*", "packages/*"],
7
  "scripts": {
8
    "build": "pnpm -r build",      // 递归构建所有包
9
    "test": "pnpm -r test"          // 递归测试所有包
10
  }
11
}

1
// tsconfig.base.json at the repo root
2
{
3
  "compilerOptions": {
4
    "target": "ES2022",                        // 目标 ECMAScript 版本
5
    "module": "ESNext",                        // 模块系统
6
    "moduleResolution": "Bundler",             // 模块解析策略
7
    "lib": ["ES2022", "DOM"],                  // 包含的类型库
8
    "strict": true,                            // 启用所有严格类型检查选项
9
    "noUncheckedIndexedAccess": true,          // 索引访问时添加 undefined 检查
10
    "exactOptionalPropertyTypes": true,        // 可选属性类型严格匹配
11
    "skipLibCheck": true,                      // 跳过声明文件检查（提升性能）
12
    "declaration": true,                       // 生成 .d.ts 声明文件
13
    "declarationMap": true,                    // 生成声明文件的 source map
14
    "verbatimModuleSyntax": true,              // 保持模块语法原样输出
15
    "isolatedModules": true                    // 确保每个文件都能独立编译
16
  }
17
}

1
// ✅ 正确：通过公开的入口导入
2
import { Button, Input } from '@acme/ui'
3

4
// ❌ 错误：直接导入内部实现
5
import { Button } from '@acme/ui/src/components/button'

1
// root package.json
2
{
3
  "scripts": {
4
    "changeset": "changeset",                  // 创建 changeset
5
    "version-packages": "changeset version",   // 更新版本号和 CHANGELOG
6
    "release": "pnpm -r build && changeset publish"  // 构建并发布
7
  }
8
}

1
// .eslintrc.cjs (root)
2
module.exports = {
3
  root: true,
4
  parser: "@typescript-eslint/parser",
5
  plugins: ["@typescript-eslint", "import"],
6
  extends: [
7
    "eslint:recommended",
8
    "plugin:@typescript-eslint/recommended"
9
  ],
10
  rules: {
11
    // 限制跨包导入路径
12
    "import/no-restricted-paths": ["error", {
13
      "zones": [
14
        // ui 包不能导入 auth 包（UI 组件不应依赖业务逻辑）
15
        {
16
          "target": "./packages/auth",
17
          "from": "./packages/ui"
18
        },
19
        // auth 包不能导入 billing 包（避免业务模块循环依赖）
20
        {
21
          "target": "./packages/billing",
22
          "from": "./packages/auth"
23
        }
24
      ]
25
    }],
26
    // 禁止循环依赖
27
    "import/no-cycle": "error"
28
  }
29
}

1
// vitest.workspace.ts at the root
2
import { defineWorkspace } from 'vitest/config'
3

4
export default defineWorkspace([
5
  // 认证模块测试
6
  {
7
    test: {
8
      include: ['packages/auth/src/**/*.test.ts']
9
    }
10
  },
11
  // UI 组件测试
12
  {
13
    test: {
14
      include: ['packages/ui/src/**/*.test.tsx']
15
    }
16
  },
17
  // Web 应用测试
18
  {
19
    test: {
20
      include: ['apps/web/src/**/*.test.tsx']
21
    }
22
  },
23
])

1
packages/auth/src/
2
  ├── login.ts
3
  ├── login.test.ts          # 测试文件与源码邻近
4
  ├── register.ts
5
  └── register.test.ts

1
// ✅ 推荐：named exports 更易重构
2
export { Button } from './Button'
3
export { Input } from './Input'
4

5
// ❌ 避免：default export 重命名时容易出错
6
export default Button

1
# @acme/auth
2

3
认证授权模块，提供登录、注册、权限验证等功能。
4

5
## 安装
6

7
\`\`\`bash
8
pnpm add @acme/auth
9
\`\`\`
10

11
## 使用示例
12

13
\`\`\`typescript
14
import { login } from '@acme/auth'
15

16
const user = await login({ email, password })
17
\`\`\`

1
# .github/CODEOWNERS
2

3
/packages/auth/     @team-security
4
/packages/billing/  @team-payments
5
/packages/ui/       @team-design-system

1
{
2
  "scripts": {
3
    "prepack": "pnpm build"  // npm publish 前自动执行
4
  }
5
}