monorepo-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Monorepo Management

Monorepo 管理

Build efficient, scalable monorepos that enable code sharing, consistent tooling, and atomic changes across multiple packages and applications.

构建高效、可扩展的Monorepo，实现多包与多应用之间的代码共享、统一工具链以及原子化变更。

When to Use This Skill

何时使用该技能

Setting up new monorepo projects
Migrating from multi-repo to monorepo
Optimizing build and test performance
Managing shared dependencies
Implementing code sharing strategies
Setting up CI/CD for monorepos
Versioning and publishing packages
Debugging monorepo-specific issues

搭建新的Monorepo项目
从多仓库架构迁移至Monorepo
优化构建与测试性能
管理共享依赖
实施代码共享策略
为Monorepo配置CI/CD
包的版本管理与发布
调试Monorepo特有的问题

Core Concepts

核心概念

1. Why Monorepos?

1. 为什么选择Monorepo？

Advantages:

Shared code and dependencies
Atomic commits across projects
Consistent tooling and standards
Easier refactoring
Simplified dependency management
Better code visibility

Challenges:

Build performance at scale
CI/CD complexity
Access control
Large Git repository

优势：

代码与依赖共享
跨项目的原子提交
统一的工具链与标准
更便捷的重构
简化的依赖管理
更清晰的代码可见性

挑战：

大规模场景下的构建性能问题
CI/CD复杂度提升
访问控制难度
Git仓库体积过大

2. Monorepo Tools

2. Monorepo工具

Package Managers:

pnpm workspaces (recommended)
npm workspaces
Yarn workspaces

Build Systems:

Turborepo (recommended for most)
Nx (feature-rich, complex)
Lerna (older, maintenance mode)

包管理器：

pnpm workspaces（推荐）
npm workspaces
Yarn workspaces

构建系统：

Turborepo（多数场景推荐）
Nx（功能丰富，复杂度较高）
Lerna（较旧，处于维护模式）

Turborepo Setup

Turborepo 初始搭建

Initial Setup

初始搭建

bash

undefined

bash

undefined

Create new monorepo

npx create-turbo@latest my-monorepo cd my-monorepo

Structure:

apps/

web/ - Next.js app

docs/ - Documentation site

packages/

ui/ - Shared UI components

config/ - Shared configurations

tsconfig/ - Shared TypeScript configs

turbo.json - Turborepo configuration

package.json - Root package.json

undefined

undefined

Configuration

配置

json

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

json

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "pnpm@8.0.0"
}

json

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

json

// package.json (root)
{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "test": "turbo run test",
    "lint": "turbo run lint",
    "format": "prettier --write \"**/*.{ts,tsx,md}\"",
    "clean": "turbo run clean && rm -rf node_modules"
  },
  "devDependencies": {
    "turbo": "^1.10.0",
    "prettier": "^3.0.0",
    "typescript": "^5.0.0"
  },
  "packageManager": "pnpm@8.0.0"
}

Package Structure

包结构

json

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "tsup": "^7.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

json

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.0",
  "private": true,
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
    "lint": "eslint src/",
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
    "@repo/tsconfig": "workspace:*",
    "tsup": "^7.0.0",
    "typescript": "^5.0.0"
  },
  "dependencies": {
    "react": "^18.2.0"
  }
}

pnpm Workspaces

Setup

搭建

yaml

undefined

yaml

undefined

pnpm-workspace.yaml

packages:

"apps/*"
"packages/*"
"tools/*"


```json
// .npmrc

packages:

"apps/*"
"packages/*"
"tools/*"


```json
// .npmrc

Hoist shared dependencies

shamefully-hoist=true

Strict peer dependencies

auto-install-peers=true strict-peer-dependencies=true

Performance

store-dir=~/.pnpm-store

undefined

store-dir=~/.pnpm-store

undefined

Dependency Management

依赖管理

bash

undefined

bash

undefined

Install dependency in specific package

pnpm add react --filter @repo/ui pnpm add -D typescript --filter @repo/ui

Install workspace dependency

pnpm add @repo/ui --filter web

Install in all packages

pnpm add -D eslint -w

Update all dependencies

pnpm update -r

Remove dependency

pnpm remove react --filter @repo/ui

undefined

pnpm remove react --filter @repo/ui

undefined

Scripts

脚本执行

bash

undefined

bash

undefined

Run script in specific package

pnpm --filter web dev pnpm --filter @repo/ui build

Run in all packages

pnpm -r build pnpm -r test

Run in parallel

pnpm -r --parallel dev

Filter by pattern

pnpm --filter "@repo/*" build pnpm --filter "...web" build # Build web and dependencies

undefined

pnpm --filter "@repo/*" build pnpm --filter "...web" build # Build web and dependencies

undefined

Nx Monorepo

Setup

搭建

bash

undefined

bash

undefined

Create Nx monorepo

npx create-nx-workspace@latest my-org

Generate applications

nx generate @nx/react:app my-app nx generate @nx/next:app my-next-app

Generate libraries

nx generate @nx/react:lib ui-components nx generate @nx/js:lib utils

undefined

nx generate @nx/react:lib ui-components nx generate @nx/js:lib utils

undefined

Configuration

配置

json

// nx.json
{
  "extends": "nx/presets/npm.json",
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": []
  }
}

json

// nx.json
{
  "extends": "nx/presets/npm.json",
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json"
    ],
    "sharedGlobals": []
  }
}

Running Tasks

任务执行

bash

undefined

bash

undefined

Run task for specific project

nx build my-app nx test ui-components nx lint utils

Run for affected projects

nx affected:build nx affected:test --base=main

Visualize dependencies

nx graph

Run in parallel

nx run-many --target=build --all --parallel=3

undefined

nx run-many --target=build --all --parallel=3

undefined

Shared Configurations

共享配置

TypeScript Configuration

TypeScript配置

json

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "incremental": true,
    "declaration": true
  },
  "exclude": ["node_modules"]
}

// packages/tsconfig/react.json
{
  "extends": "./base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/tsconfig/react.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

json

// packages/tsconfig/base.json
{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "incremental": true,
    "declaration": true
  },
  "exclude": ["node_modules"]
}

// packages/tsconfig/react.json
{
  "extends": "./base.json",
  "compilerOptions": {
    "jsx": "react-jsx",
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
  }
}

// apps/web/tsconfig.json
{
  "extends": "@repo/tsconfig/react.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

ESLint Configuration

ESLint配置

javascript

// packages/config/eslint-preset.js
module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "prettier",
  ],
  plugins: ["@typescript-eslint", "react", "react-hooks"],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,
    },
  },
  settings: {
    react: {
      version: "detect",
    },
  },
  rules: {
    "@typescript-eslint/no-unused-vars": "error",
    "react/react-in-jsx-scope": "off",
  },
};

// apps/web/.eslintrc.js
module.exports = {
  extends: ["@repo/config/eslint-preset"],
  rules: {
    // App-specific rules
  },
};

javascript

// packages/config/eslint-preset.js
module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "prettier",
  ],
  plugins: ["@typescript-eslint", "react", "react-hooks"],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,
    },
  },
  settings: {
    react: {
      version: "detect",
    },
  },
  rules: {
    "@typescript-eslint/no-unused-vars": "error",
    "react/react-in-jsx-scope": "off",
  },
};

// apps/web/.eslintrc.js
module.exports = {
  extends: ["@repo/config/eslint-preset"],
  rules: {
    // App-specific rules
  },
};

Code Sharing Patterns

代码共享模式

Pattern 1: Shared UI Components

模式1：共享UI组件

typescript

// packages/ui/src/button.tsx
import * as React from 'react';

export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// packages/ui/src/index.ts
export { Button, type ButtonProps } from './button';
export { Input, type InputProps } from './input';

// apps/web/src/app.tsx
import { Button } from '@repo/ui';

export function App() {
  return <Button variant="primary">Click me</Button>;
}

typescript

// packages/ui/src/button.tsx
import * as React from 'react';

export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button
      className={`btn btn-${variant}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

// packages/ui/src/index.ts
export { Button, type ButtonProps } from './button';
export { Input, type InputProps } from './input';

// apps/web/src/app.tsx
import { Button } from '@repo/ui';

export function App() {
  return <Button variant="primary">Click me</Button>;
}

Pattern 2: Shared Utilities

模式2：共享工具函数

typescript

// packages/utils/src/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function truncate(str: string, length: number): string {
  return str.length > length ? str.slice(0, length) + "..." : str;
}

// packages/utils/src/index.ts
export * from "./string";
export * from "./array";
export * from "./date";

// Usage in apps
import { capitalize, truncate } from "@repo/utils";

typescript

// packages/utils/src/string.ts
export function capitalize(str: string): string {
  return str.charAt(0).toUpperCase() + str.slice(1);
}

export function truncate(str: string, length: number): string {
  return str.length > length ? str.slice(0, length) + "..." : str;
}

// packages/utils/src/index.ts
export * from "./string";
export * from "./array";
export * from "./date";

// Usage in apps
import { capitalize, truncate } from "@repo/utils";

Pattern 3: Shared Types

模式3：共享类型定义

typescript

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user";
}

export interface CreateUserInput {
  email: string;
  name: string;
  password: string;
}

// Used in both frontend and backend
import type { User, CreateUserInput } from "@repo/types";

typescript

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user";
}

export interface CreateUserInput {
  email: string;
  name: string;
  password: string;
}

// Used in both frontend and backend
import type { User, CreateUserInput } from "@repo/types";

Build Optimization

构建优化

Turborepo Caching

Turborepo缓存

json

// turbo.json
{
  "pipeline": {
    "build": {
      // Build depends on dependencies being built first
      "dependsOn": ["^build"],

      // Cache these outputs
      "outputs": ["dist/**", ".next/**"],

      // Cache based on these inputs (default: all files)
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "package.json"]
    },
    "test": {
      // Run tests in parallel, don't depend on build
      "cache": true,
      "outputs": ["coverage/**"]
    }
  }
}

json

// turbo.json
{
  "pipeline": {
    "build": {
      // Build depends on dependencies being built first
      "dependsOn": ["^build"],

      // Cache these outputs
      "outputs": ["dist/**", ".next/**"],

      // Cache based on these inputs (default: all files)
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "package.json"]
    },
    "test": {
      // Run tests in parallel, don't depend on build
      "cache": true,
      "outputs": ["coverage/**"]
    }
  }
}

Remote Caching

远程缓存

bash

undefined

bash

undefined

Turborepo Remote Cache (Vercel)

npx turbo login npx turbo link

Custom remote cache

turbo.json

{ "remoteCache": { "signature": true, "enabled": true } }

undefined

{ "remoteCache": { "signature": true, "enabled": true } }

undefined

CI/CD for Monorepos

Monorepo的CI/CD配置

GitHub Actions

yaml

undefined

yaml

undefined

.github/workflows/ci.yml

name: CI

on: push: branches: [main] pull_request: branches: [main]

jobs: build: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v3
    with:
      fetch-depth: 0 # For Nx affected commands

  - uses: pnpm/action-setup@v2
    with:
      version: 8

  - uses: actions/setup-node@v3
    with:
      node-version: 18
      cache: "pnpm"

  - name: Install dependencies
    run: pnpm install --frozen-lockfile

  - name: Build
    run: pnpm turbo run build

  - name: Test
    run: pnpm turbo run test

  - name: Lint
    run: pnpm turbo run lint

  - name: Type check
    run: pnpm turbo run type-check

undefined

name: CI

on: push: branches: [main] pull_request: branches: [main]

jobs: build: runs-on: ubuntu-latest

steps:
  - uses: actions/checkout@v3
    with:
      fetch-depth: 0 # For Nx affected commands

  - uses: pnpm/action-setup@v2
    with:
      version: 8

  - uses: actions/setup-node@v3
    with:
      node-version: 18
      cache: "pnpm"

  - name: Install dependencies
    run: pnpm install --frozen-lockfile

  - name: Build
    run: pnpm turbo run build

  - name: Test
    run: pnpm turbo run test

  - name: Lint
    run: pnpm turbo run lint

  - name: Type check
    run: pnpm turbo run type-check

undefined

Deploy Affected Only

仅部署变更的应用

yaml

undefined

yaml

undefined

Deploy only changed apps

name: Deploy affected apps run: | if pnpm nx affected:apps --base=origin/main --head=HEAD | grep -q "web"; then echo "Deploying web app" pnpm --filter web deploy fi

undefined

name: Deploy affected apps run: | if pnpm nx affected:apps --base=origin/main --head=HEAD | grep -q "web"; then echo "Deploying web app" pnpm --filter web deploy fi

undefined

Best Practices

最佳实践

Consistent Versioning: Lock dependency versions across workspace
Shared Configs: Centralize ESLint, TypeScript, Prettier configs
Dependency Graph: Keep it acyclic, avoid circular dependencies
Cache Effectively: Configure inputs/outputs correctly
Type Safety: Share types between frontend/backend
Testing Strategy: Unit tests in packages, E2E in apps
Documentation: README in each package
Release Strategy: Use changesets for versioning

统一版本控制：锁定工作区内所有依赖的版本
共享配置：集中管理ESLint、TypeScript、Prettier配置
依赖图管理：保持依赖无环，避免循环依赖
高效缓存：正确配置缓存的输入与输出项
类型安全：前后端共享类型定义
测试策略：包内编写单元测试，应用内编写端到端测试
文档规范：为每个包添加README文档
发布策略：使用Changesets进行版本管理

Common Pitfalls

常见陷阱

Circular Dependencies: A depends on B, B depends on A
Phantom Dependencies: Using deps not in package.json
Incorrect Cache Inputs: Missing files in Turborepo inputs
Over-Sharing: Sharing code that should be separate
Under-Sharing: Duplicating code across packages
Large Monorepos: Without proper tooling, builds slow down

循环依赖：A依赖B，B又依赖A
幽灵依赖：使用未在package.json中声明的依赖
缓存配置错误：Turborepo输入项遗漏文件
过度共享：共享本应独立的代码
共享不足：在多个包中重复代码
大规模Monorepo：缺乏合适工具导致构建速度变慢

Publishing Packages

包发布

bash

undefined

bash

undefined

Using Changesets

pnpm add -Dw @changesets/cli pnpm changeset init

Create changeset

pnpm changeset

Version packages

pnpm changeset version

Publish

pnpm changeset publish


```yaml

pnpm changeset publish


```yaml

.github/workflows/release.yml

name: Create Release Pull Request or Publish uses: changesets/action@v1 with: publish: pnpm release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

undefined

name: Create Release Pull Request or Publish uses: changesets/action@v1 with: publish: pnpm release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

undefined

Resources

参考资源

references/turborepo-guide.md: Comprehensive Turborepo documentation
references/nx-guide.md: Nx monorepo patterns
references/pnpm-workspaces.md: pnpm workspace features
assets/monorepo-checklist.md: Setup checklist
assets/migration-guide.md: Multi-repo to monorepo migration
scripts/dependency-graph.ts: Visualize package dependencies

references/turborepo-guide.md：Turborepo完整文档
references/nx-guide.md：Nx Monorepo模式指南
references/pnpm-workspaces.md：pnpm工作区功能说明
assets/monorepo-checklist.md：Monorepo搭建检查清单
assets/migration-guide.md：多仓库转Monorepo迁移指南
scripts/dependency-graph.ts：可视化包依赖关系脚本