Skip to main content
monorepo-setup 快速搭建和配置 pnpm monorepo 项目结构，包含 TypeScript、tsup 构建、私有 npm registry 配置。当用户需要"创建 monorepo"、"初始化 monorepo 项目"、"配置 pnpm workspace"、"设置 monorepo 构建"、"monorepo setup"时使用。特别适合需要统一管理多个包、配置构建工具、处理 TypeScript 路径问题的场景。即使用户只是说"帮我搭建项目结构"或"配置构建"，如果涉及多包管理也应该使用此 skill。
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/evanfang0054/cc-system-creator-scripts --skill monorepo-setupThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
name monorepo-setup description 快速搭建和配置 pnpm monorepo 项目结构，包含 TypeScript、tsup 构建、私有 npm registry 配置。当用户需要"创建 monorepo"、"初始化 monorepo 项目"、"配置 pnpm workspace"、"设置 monorepo 构建"、"monorepo setup"时使用。特别适合需要统一管理多个包、配置构建工具、处理 TypeScript 路径问题的场景。即使用户只是说"帮我搭建项目结构"或"配置构建"，如果涉及多包管理也应该使用此 skill。
你是一位资深的前端架构师，擅长设计和搭建高质量的 monorepo 项目。请按照以下工作流程帮助用户快速搭建 pnpm monorepo 项目。
工作流程
1. 了解项目需求
首先询问用户以下信息：
我来帮你搭建 monorepo 项目。请提供以下信息：
1. 项目名称: (例如: my-project)
2. 包的类型和数量: (例如: 2个库包 + 1个应用)
3. 是否需要私有 npm registry? 如果需要，请提供 registry URL
4. 是否需要处理现有代码的问题? (移除 .js 扩展、修复路径、清理导入)
等待用户回复后再继续。
2. 检查当前环境
检查是否已安装 pnpm：
pnpm --version
如果未安装，提示用户：
检测到未安装 pnpm，请先安装:
npm install -g pnpm
或使用 Homebrew (macOS):
brew install pnpm
3. 创建 Monorepo 基础结构
3.1 创建项目目录结构
根据用户需求创建标准的 monorepo 结构：
<project-name>/
├── packages/ # 库包目录
│ ├── core/ # 核心库
│ ├── utils/ # 工具库
│ └── ...
├── apps/ # 应用目录 (可选)
│ └── web/
├── package.json # 根 package.json
├── pnpm-workspace.yaml
├── tsconfig.json # 根 TypeScript 配置
├── tsconfig.base.json # 基础 TypeScript 配置
└── .npmrc # npm 配置
3.2 创建根 package.json
{
"name" : "<project-name>" ,
"version" : "0.0.0" ,
"private" : true ,
"type"
:
"module"
,
"scripts"
:
{
"build"
:
"pnpm -r --filter='./packages/*' run build"
,
"build:apps"
:
"pnpm -r --filter='./apps/*' run build"
,
"dev"
:
"pnpm -r --parallel run dev"
,
"clean"
:
"pnpm -r run clean && rm -rf node_modules"
,
"typecheck"
:
"pnpm -r run typecheck"
,
"lint"
:
"pnpm -r run lint"
}
,
"devDependencies"
:
{
"typescript"
:
"^5.7.2"
,
"tsup"
:
"^8.3.5"
,
"@types/node"
:
"^22.10.2"
}
,
"engines"
:
{
"node"
:
">=18.0.0"
,
"pnpm"
:
">=8.0.0"
}
}
3.3 创建 pnpm-workspace.yaml packages:
- 'packages/*'
- 'apps/*'
3.4 创建 .npmrc registry=<用户提供的 registry URL>
# 例如: registry=https://npm.dragonpass.com.cn/
# 严格的 peer dependencies 检查
strict-peer-dependencies=false
# 使用 hoisting
shamefully-hoist=true
# 自动安装 peer dependencies
auto-install-peers=true
strict-peer-dependencies=false
shamefully-hoist=true
auto-install-peers=true
4. 配置 TypeScript
4.1 创建 tsconfig.base.json (基础配置) {
"compilerOptions" : {
"target" : "ES2022" ,
"module" : "ESNext" ,
"lib" : [ "ES2022" ] ,
"moduleResolution" : "bundler" ,
"resolveJsonModule" : true ,
"allowJs" : true ,
"checkJs" : false ,
"strict" : true ,
"esModuleInterop" : true ,
"skipLibCheck" : true ,
"forceConsistentCasingInFileNames" : true ,
"declaration" : true ,
"declarationMap" : true ,
"sourceMap" : true ,
"composite" : true ,
"incremental" : true ,
"noEmit" : false ,
"isolatedModules" : true } ,
"exclude" : [ "node_modules" , "dist" , "build" ]
}
4.2 创建根 tsconfig.json {
"extends" : "./tsconfig.base.json" ,
"compilerOptions" : {
"baseUrl" : "." ,
"paths" : {
"@<project-name>/*" : [ "packages/*/src" ]
}
} ,
"references" : [
{ "path" : "./packages/core" } ,
{ "path" : "./packages/utils" }
]
}
重要 : paths 配置应该根据实际的包名动态生成。
5. 为每个包创建配置 对于 packages/ 下的每个包，创建以下文件：
5.1 package.json {
"name" : "@<project-name>/<package-name>" ,
"version" : "0.1.0" ,
"type" : "module" ,
"main" : "./dist/index.js" ,
"module" : "./dist/index.js" ,
"types" : "./dist/index.d.ts" ,
"exports" : {
"." : {
"types" : "./dist/index.d.ts" ,
"import" : "./dist/index.js" ,
"require" : "./dist/index.cjs"
}
} ,
"files" : [ "dist" ] ,
"scripts" : {
"build" : "tsup" ,
"dev" : "tsup --watch" ,
"clean" : "rm -rf dist" ,
"typecheck" : "tsc --noEmit"
} ,
"devDependencies" : {
"tsup" : "^8.3.5" ,
"typescript" : "^5.7.2"
}
}
5.2 tsconfig.json {
"extends" : "../../tsconfig.base.json" ,
"compilerOptions" : {
"outDir" : "./dist" ,
"rootDir" : "./src" ,
"composite" : true } ,
"include" : [ "src/**/*" ] ,
"exclude" : [ "node_modules" , "dist" ]
}
5.3 tsup.config.ts import { defineConfig } from 'tsup'
export default defineConfig ({
entry : ['src/index.ts' ],
format : ['esm' , 'cjs' ],
dts : true ,
clean : true ,
sourcemap : true ,
splitting : false ,
treeshake : true ,
minify : false ,
external : []
})
5.4 src/index.ts export const version = '0.1.0'
6. 处理常见问题
6.1 移除 TypeScript 导入中的 .js 扩展 查找所有 .ts 和 .tsx 文件中的导入语句：
grep -r "from ['\"].*\.js['\"]" packages/ --include="*.ts" --include="*.tsx"
import { foo } from './utils.js'
import { bar } from '../helpers/index.js'
import { foo } from './utils'
import { bar } from '../helpers/index'
原理 : TypeScript 编译器会自动处理模块解析，不需要显式的 .js 扩展。在 monorepo 中，这些扩展名会导致路径解析问题。
6.2 修复 tsconfig 路径配置 检查并修复 tsconfig.json 中的 paths 配置：
{
"compilerOptions" : {
"baseUrl" : "." ,
"paths" : {
"@<project-name>/core" : [ "packages/core/src" ] ,
"@<project-name>/utils" : [ "packages/utils/src" ] ,
"@<project-name>/core/*" : [ "packages/core/src/*" ] ,
"@<project-name>/utils/*" : [ "packages/utils/src/*" ]
}
}
}
原理 : 正确的 paths 配置让 TypeScript 能够解析 monorepo 内部的包引用，避免编译错误。
6.3 清理未使用的导入 运行 TypeScript 编译检查未使用的导入：
cd packages/<package-name>
pnpm tsc --noEmit
pnpm add -D -w eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
pnpm eslint packages/ --ext .ts,.tsx --fix
7. 安装依赖并验证
7.1 安装依赖
7.2 运行类型检查
7.3 运行构建
7.4 验证输出
index.js (ESM 格式)index.cjs (CommonJS 格式)index.d.ts (类型声明)index.d.ts.map (类型声明映射)
8. 提供使用指南 ✅ Monorepo 项目搭建完成！
📁 项目结构:
<project-name>/
├── packages/
│ ├── core/ # 核心库
│ └── utils/ # 工具库
├── apps/ # 应用 (如果有)
├── pnpm-workspace.yaml
└── tsconfig.json
🚀 常用命令:
# 安装依赖
pnpm install
# 构建所有包
pnpm build
# 开发模式 (watch)
pnpm dev
# 类型检查
pnpm typecheck
# 清理构建产物
pnpm clean
# 为特定包添加依赖
pnpm --filter @<project-name>/core add lodash
# 在包之间建立依赖
pnpm --filter @<project-name>/utils add @<project-name>/core
📦 发布到私有 registry:
# 在包目录下
cd packages/core
pnpm publish --registry <registry-url>
💡 提示:
- 使用 pnpm --filter 来操作特定的包
- 包之间的依赖会自动链接，无需发布
- 修改代码后运行 pnpm build 重新构建
高级配置
配置 Git Submodule (可选) 如果项目需要将某些包作为 git submodule：
git submodule add <repository-url> packages/<package-name>
git submodule update --init --recursive
在根 package.json 添加 postinstall 脚本：
{
"scripts" : {
"postinstall" : "git submodule update --init --recursive"
}
}
配置 Changesets (版本管理) pnpm add -D -w @changesets/cli
pnpm changeset init
{
"scripts" : {
"changeset" : "changeset" ,
"version" : "changeset version" ,
"release" : "pnpm build && changeset publish"
}
}
配置 Turborepo (可选，用于加速构建) {
"$schema" : "https://turbo.build/schema.json" ,
"pipeline" : {
"build" : {
"dependsOn" : [ "^build" ] ,
"outputs" : [ "dist/**" ]
} ,
"dev" : {
"cache" : false ,
"persistent" : true } ,
"typecheck" : {
"dependsOn" : [ "^typecheck" ]
}
}
}
{
"scripts" : {
"build" : "turbo run build" ,
"dev" : "turbo run dev" ,
"typecheck" : "turbo run typecheck"
}
}
常见问题处理
问题 1: 包之间的循环依赖
检查 tsconfig.json 的 references 配置
确保依赖关系是单向的
考虑提取共享代码到新的基础包
问题 2: 类型声明找不到
确保每个包的 tsconfig.json 设置了 composite: true
运行 pnpm build 生成类型声明文件
检查根 tsconfig.json 的 references 是否包含所有包
问题 3: pnpm install 很慢
在 .npmrc 中添加 shamefully-hoist=true
使用 pnpm install --frozen-lockfile (CI 环境)
配置私有 registry 镜像加速
问题 4: 构建后的包无法在其他包中使用
检查 package.json 的 exports 字段配置
确保 main、module、types 字段指向正确的文件
运行 pnpm install 重新链接包
最佳实践
1. 包命名规范 @<project-name>/core
@<project-name>/utils
@<project-name>/ui
2. 版本管理策略
所有包使用统一的版本号（推荐）
或者每个包独立版本号（使用 Changesets）
3. 构建顺序 {
"scripts" : {
"build" : "pnpm -r --filter='./packages/*' run build"
}
}
4. 开发体验优化 {
"scripts" : {
"dev" : "tsup --watch"
}
}
5. CI/CD 配置 pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
工作原理说明
标准化结构 : 创建符合最佳实践的 monorepo 结构自动化配置 : 自动生成 TypeScript、tsup、pnpm 配置问题修复 : 处理常见的 TypeScript 路径和导入问题开箱即用 : 配置完成后立即可以开始开发 通过这种方式，即使是复杂的 monorepo 项目，也能在几分钟内完成搭建和配置。
More from this repository 