pnpm Workspace

pnpm Workspace 用于在一个仓库中管理多个 package。根目录必须包含 pnpm-workspace.yaml。

目录规划

./
├── apps/                         # 可运行应用
│   ├── web/                      # Web 应用
│   │   └── package.json
│   ├── admin/                    # 管理后台
│   │   └── package.json
│   └── api/                      # API 服务
│       └── package.json
├── packages/                     # 可复用 package
│   ├── ui/                       # UI 组件库
│   │   └── package.json
│   ├── utils/                    # 工具函数库
│   │   └── package.json
│   ├── eslint-config/            # ESLint 配置包
│   │   └── package.json
│   └── tsconfig/                 # TypeScript 配置包
│       └── package.json
├── package.json                  # 根 package
├── pnpm-workspace.yaml           # Workspace 配置
├── pnpm-lock.yaml                # 全仓统一锁文件
├── .npmrc                        # npm registry、认证、pnpm 配置
└── turbo.json                    # 可选：Turborepo 任务编排配置

目录命名没有强制标准，但通常保持以下约定：

• apps/ 放最终运行或部署的应用。
• packages/ 放可被其他 package 引用的库、组件、配置。
• 根目录只放仓库级配置和脚本，避免承载具体业务代码。

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'packages/*'

根 package 默认属于 Workspace，无需显式写入 packages。

可以使用 ! 排除目录：

packages:
  - 'apps/*'
  - 'packages/*'
  - '!**/test/**'

根目录 package.json

根 package 用于维护仓库级脚本、开发工具和统一约束。

{
  "name": "vfan-monorepo",
  "private": true,
  "packageManager": "pnpm@11.10.0",
  "engines": {
    "node": ">=22.0.0",
    "pnpm": ">=11.0.0"
  },
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo build",
    "lint": "turbo lint",
    "test": "turbo test"
  },
  "devDependencies": {
    "turbo": "^2.0.0"
  }
}

注意：

• Monorepo 根目录通常设置 "private": true，避免误发布整个仓库。
• 根目录依赖只属于根 package，不会自动成为所有子包的依赖。
• 某个应用或库实际使用的依赖，必须在自己的 package.json 中声明。
• 根目录通常放 turbo、typescript、eslint、prettier 等仓库级开发工具。

子包 package.json

应用 package 示例：

{
  "name": "@vfan-monorepo/web",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  },
  "dependencies": {
    "react": "^19.0.0"
  }
}

可发布库示例：

{
  "name": "@vfan-monorepo/ui",
  "version": "1.0.0",
  "exports": {
    ".": "./src/index.ts"
  },
  "peerDependencies": {
    "react": "^19.0.0"
  }
}

应用通常设置 "private": true；可发布库需要维护 name、version、exports、peerDependencies 等字段。