monorepo + turborepo 搭建项目

organization/
├── project-a/        (独立仓库)
│   ├── .git/
│   └── package.json
├── project-b/        (独立仓库)
│   ├── .git/
│   └── package.json
└── project-c/        (独立仓库)
    ├── .git/
    └── package.json

my-monorepo/
├── .git/             (单一仓库)
├── package.json      (根配置)
├── packages/
│   ├── package-a/
│   │   └── package.json
│   ├── package-b/
│   │   └── package.json
│   └── package-c/
│       └── package.json

# 检查版本
node -v  # 需要 v18.0.0 或更高
npm -v   # 需要 v9.0.0 或更高

# 通过 npm 安装
npm install -g pnpm

# 检查版本
pnpm -v  # 需要 v8.0.0 或更高

# 创建并进入项目目录
mkdir my-monorepo
cd my-monorepo

# 初始化 Git
git init

# 创建 .gitignore
cat > .gitignore << EOF
node_modules
dist
.DS_Store
*.log
.turbo
.env.local
EOF

pnpm init

{
  "name": "my-monorepo",
  "version": "1.0.0",
  "private": true,
  "description": "My awesome monorepo project",
  "scripts": {
    "dev": "pnpm --parallel --recursive run dev",
    "build": "pnpm --recursive run build",
    "lint": "pnpm --recursive run lint",
    "test": "pnpm --recursive run test",
    "clean": "pnpm --recursive run clean && rm -rf node_modules"
  },
  "keywords": ["monorepo"],
  "author": "Your Name",
  "license": "MIT",
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=8.0.0"
  }
}

packages:
  # 所有在 packages 目录下的包
  - "packages/*"
  # 所有在 apps 目录下的应用
  - "apps/*"
  # 排除测试目录
  - "!**/test/**"
  - "!**/node_modules/**"

packages:
  # 精确匹配单个包
  - "my-app"

  # packages 目录下的直接子目录
  - "packages/*"

  # packages 目录下的所有子目录（递归）
  - "packages/**"

  # 多个目录
  - "apps/*"
  - "packages/*"
  - "tools/*"

  # 排除模式
  - "!**/test/**"
  - "!**/*.test.ts"
  - "!**/node_modules/**"

# pnpm-workspace.yaml
packages:
  - "packages/*"
  - "apps/*"

# catalog（pnpm 9.0+）：统一管理依赖版本
catalog:
  react: ^18.3.0
  typescript: ^5.3.3
  vite: ^5.0.0

{
  "dependencies": {
    "react": "catalog:",
    "typescript": "catalog:"
  }
}

# 创建目录
mkdir -p packages apps

# 创建基础结构
mkdir -p packages/shared
mkdir -p packages/ui
mkdir -p apps/web
mkdir -p apps/docs

my-monorepo/
├── .git/
├── .gitignore
├── package.json
├── pnpm-workspace.yaml
├── packages/          # 共享包
│   ├── shared/        # 共享工具
│   └── ui/            # UI 组件库
└── apps/              # 应用
    ├── web/           # 主应用
    └── docs/          # 文档站点

cd packages/shared
pnpm init

{
  "name": "@my-monorepo/shared",
  "version": "1.0.0",
  "description": "Shared utilities and helpers",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    }
  },
  "files": ["dist"],
  "scripts": {
    "dev": "tsup src/index.ts --watch --format cjs,esm --dts",
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "clean": "rm -rf dist"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.3.3"
  }
}

/**
 * 格式化日期
 */
export function formatDate(date: Date): string {
  return date.toLocaleDateString("zh-CN");
}

/**
 * 延迟函数
 */
export function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

/**
 * 生成随机ID
 */
export function generateId(): string {
  return Math.random().toString(36).substring(2, 15);
}

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"],
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

cd ../../packages/ui
pnpm init

{
  "name": "@my-monorepo/ui",
  "version": "1.0.0",
  "description": "Shared UI components",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    },
    "./style.css": "./dist/style.css"
  },
  "files": ["dist"],
  "scripts": {
    "dev": "tsup src/index.ts --watch --format cjs,esm --dts",
    "build": "tsup src/index.ts --format cjs,esm --dts",
    "clean": "rm -rf dist"
  },
  "dependencies": {
    "@my-monorepo/shared": "workspace:*"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.3.3"
  }
}

import { generateId } from "@my-monorepo/shared";

export interface ButtonProps {
  text: string;
  onClick?: () => void;
}

export class Button {
  private id: string;
  private element: HTMLButtonElement;

  constructor(props: ButtonProps) {
    this.id = generateId();
    this.element = document.createElement("button");
    this.element.textContent = props.text;
    this.element.id = this.id;

    if (props.onClick) {
      this.element.addEventListener("click", props.onClick);
    }
  }

  render(container: HTMLElement): void {
    container.appendChild(this.element);
  }
}

export { Button } from "./Button";
export type { ButtonProps } from "./Button";

{
  "extends": "../shared/tsconfig.json",
  "compilerOptions": {
    "lib": ["ES2020", "DOM"],
    "rootDir": "./src"
  }
}

cd ../..

# 安装所有依赖
pnpm install

cd apps/web

# 使用 Vite 创建 Vue 3 项目
pnpm create vite . --template vue-ts

{
  "name": "@my-monorepo/web",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.4.0",
    "@my-monorepo/shared": "workspace:*",
    "@my-monorepo/ui": "workspace:*"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^5.0.0",
    "typescript": "^5.3.3",
    "vite": "^5.0.0",
    "vue-tsc": "^1.8.0"
  }
}

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";

export default defineConfig({
  plugins: [vue()],
  server: {
    port: 3000,
  },
});

<script setup lang="ts">
import { ref, onMounted } from "vue";
import { formatDate, generateId } from "@my-monorepo/shared";

const currentDate = ref("");
const uniqueId = ref("");

onMounted(() => {
  currentDate.value = formatDate(new Date());
  uniqueId.value = generateId();
});
</script>

<template>
  <div class="app">
    <h1>My Monorepo Web App</h1>
    <p>Current Date: {{ currentDate }}</p>
    <p>Unique ID: {{ uniqueId }}</p>
  </div>
</template>

<style scoped>
.app {
  padding: 2rem;
  font-family: sans-serif;
}

h1 {
  color: #42b883;
}
</style>

cd ../docs

# 初始化 VitePress
pnpm init
pnpm add -D vitepress vue

{
  "name": "@my-monorepo/docs",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "vitepress dev",
    "build": "vitepress build",
    "preview": "vitepress preview"
  },
  "devDependencies": {
    "vitepress": "^1.0.0",
    "vue": "^3.4.0"
  }
}

import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Monorepo Docs",
  description: "Documentation for my monorepo project",
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" },
    ],
    sidebar: [
      {
        text: "Guide",
        items: [
          { text: "Getting Started", link: "/guide/" },
          { text: "Shared Utils", link: "/guide/shared" },
          { text: "UI Components", link: "/guide/ui" },
        ],
      },
    ],
  },
});

---
layout: home
title: Home
---

# My Monorepo

Welcome to the documentation!

## Features

- 🚀 Fast and efficient
- 📦 Well organized
- 🛠️ Easy to maintain

# Getting Started

This is a monorepo project built with pnpm workspaces.

## Installation

\`\`\`bash
pnpm install
\`\`\`

## Development

\`\`\`bash
pnpm dev
\`\`\`

cd ../..
pnpm install

pnpm add -D turbo

{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    },
    "clean": {
      "cache": false
    }
  }
}

// ❌ Turborepo 1.x（旧语法）
{
  "pipeline": {
    "build": { ... }
  }
}

// ✅ Turborepo 2.x（新语法）
{
  "tasks": {
    "build": { ... }
  }
}

# 自动迁移配置到 Turborepo 2.x
npx @turbo/codemod migrate

# 单独迁移特定项
npx @turbo/codemod update-schema-json-url    # 更新 schema URL
npx @turbo/codemod migrate-dot-env            # 迁移 dotEnv 配置
npx @turbo/codemod migrate-env-var-dependencies  # 迁移环境变量依赖

{
  "name": "my-monorepo",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "dev": "turbo run dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "clean": "turbo run clean && rm -rf node_modules .turbo"
  },
  "devDependencies": {
    "turbo": "^2.6.1"
  },
  "engines": {
    "node": ">=18.0.0",
    "pnpm": ">=9.0.0"
  },
  "packageManager": "pnpm@9.15.0"
}

## 第五步：配置代码规范

### 5.1 安装 ESLint 和 Prettier

```bash
pnpm add -D eslint prettier \
  @typescript-eslint/eslint-plugin \
  @typescript-eslint/parser \
  eslint-config-prettier \
  eslint-plugin-prettier

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended",
  ],
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2021,
    sourceType: "module",
  },
  plugins: ["@typescript-eslint"],
  rules: {
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-unused-vars": [
      "error",
      {
        argsIgnorePattern: "^_",
        varsIgnorePattern: "^_",
      },
    ],
  },
};

{
  "semi": true,
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "trailingComma": "es5",
  "arrowParens": "always",
  "endOfLine": "lf"
}

cat > .eslintignore << EOF
node_modules
dist
.turbo
*.config.js
*.config.ts
EOF

cp .eslintignore .prettierignore

{
  "scripts": {
    "lint": "eslint . --ext .ts,.tsx,.js,.jsx,.vue"
  }
}

pnpm add -D husky lint-staged
npx husky init

{
  "scripts": {
    "prepare": "husky"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml,yaml}": ["prettier --write"]
  }
}

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

# 构建 shared 包
cd packages/shared
pnpm build

# 构建 ui 包
cd ../ui
pnpm build

# 回到根目录
cd ../..

# 启动所有 dev 服务器
pnpm dev

# 或单独启动
pnpm --filter @my-monorepo/web dev
pnpm --filter @my-monorepo/docs dev

pnpm build

my-monorepo/
├── .git/
├── .gitignore
├── .eslintrc.cjs
├── .eslintignore
├── .prettierrc.json
├── .prettierignore
├── .husky/
│   └── pre-commit
├── package.json
├── pnpm-workspace.yaml
├── pnpm-lock.yaml
├── turbo.json
├── tsconfig.json
├── packages/
│   ├── shared/
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── dist/
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── ui/
│       ├── src/
│       │   ├── Button.ts
│       │   └── index.ts
│       ├── dist/
│       ├── package.json
│       └── tsconfig.json
└── apps/
    ├── web/
    │   ├── src/
    │   │   ├── App.vue
    │   │   └── main.ts
    │   ├── public/
    │   ├── index.html
    │   ├── package.json
    │   ├── tsconfig.json
    │   └── vite.config.ts
    └── docs/
        ├── .vitepress/
        │   └── config.ts
        ├── guide/
        │   ├── index.md
        │   ├── shared.md
        │   └── ui.md
        ├── index.md
        └── package.json

# 安装所有依赖
pnpm install

# 添加根目录依赖
pnpm add -D typescript -w

# 为特定包添加依赖
pnpm --filter @my-monorepo/web add vue-router

# 为所有包添加依赖
pnpm --recursive add lodash

# 删除依赖
pnpm --filter @my-monorepo/web remove axios

# 在所有包中执行
pnpm --recursive run build

# 并行执行
pnpm --parallel --recursive run dev

# 在特定包中执行
pnpm --filter @my-monorepo/web dev

# 在多个包中执行
pnpm --filter @my-monorepo/web --filter @my-monorepo/docs dev

# 构建（会自动处理依赖顺序）
turbo run build

# 开发模式
turbo run dev

# Watch 模式（Turborepo 2.0 新特性）
turbo watch dev
# 自动检测文件变化并重新运行任务

# 只构建特定包及其依赖
turbo run build --filter=@my-monorepo/web

# 强制重新构建（忽略缓存）
turbo run build --force

# 查看依赖图
turbo run build --graph

# 查看任务执行摘要
turbo run build --summarize

# 监听文件变化，自动重新运行
turbo watch dev
turbo watch build
turbo watch lint

# 等价于传统的 nodemon/chokidar，但使用 Turborepo 的依赖图

# 启用交互式 TUI（默认启用）
turbo run dev --ui=tui

# 使用传统流式输出
turbo run dev --ui=stream

# 只运行指定包
turbo run build --filter=@my-monorepo/web

# 运行多个包
turbo run build --filter=@my-monorepo/web --filter=@my-monorepo/docs

# 运行包及其依赖
turbo run build --filter=@my-monorepo/web...

# 运行包及其依赖者
turbo run build --filter=...@my-monorepo/shared

# 清理所有 dist
pnpm clean

# 清理所有 node_modules
pnpm --recursive exec rm -rf node_modules
rm -rf node_modules

# 重新安装
pnpm install

{
  "scripts": {
    "prepublishOnly": "pnpm build"
  },
  "publishConfig": {
    "access": "public"
  }
}

cd packages/shared
pnpm publish

pnpm add -D @changesets/cli
pnpm changeset init

pnpm changeset

# 更新版本
pnpm changeset version

# 构建
pnpm build

# 发布
pnpm changeset publish

包命名：@scope/package-name
├── @my-monorepo/shared       ✅ 共享工具
├── @my-monorepo/ui            ✅ UI 组件
├── @my-monorepo/web           ✅ Web 应用
└── @my-monorepo/docs          ✅ 文档站点

{
  "dependencies": {
    "@my-monorepo/shared": "workspace:*", // 使用最新版本
    "@my-monorepo/ui": "workspace:^1.0.0" // 指定版本范围
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"] // ^ 表示依赖的包
    }
  }
}

{
  "tasks": {
    "build": {
      // ✅ ^build - 先运行依赖包的 build
      "dependsOn": ["^build"]
    },
    "test": {
      // ✅ build - 先运行当前包的 build
      // ✅ ^build - 然后运行依赖包的 build
      "dependsOn": ["build", "^build"]
    },
    "deploy": {
      // ✅ build, test - 按顺序运行当前包的任务
      "dependsOn": ["build", "test"]
    }
  }
}

feat(web): 添加用户登录功能
fix(shared): 修复日期格式化 bug
docs(ui): 更新 Button 组件文档
chore: 升级依赖版本

name: CI

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

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - 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

      - name: Lint
        run: pnpm lint

      - name: Build
        run: pnpm build

      - name: Test
        run: pnpm test

{
  "tasks": {
    "build": {
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"]
    }
  }
}

{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "env": ["DATABASE_URL", "API_KEY"], // 环境变量影响缓存
      "inputs": ["src/**/*.ts", "!src/**/*.test.ts"] // 测试文件不影响构建缓存
    }
  }
}

pnpm install --parallel

# .npmrc
# 提升依赖到根 node_modules（提高兼容性）
shamefully-hoist=true

# 不严格检查 peer 依赖（避免冲突）
strict-peer-dependencies=false

# 自动安装 peer dependencies（pnpm 9.x）
auto-install-peers=true

# 使用符号链接（节省空间）
symlink=true

# 登录 Vercel（免费提供远程缓存）
npx turbo login

# 链接项目
npx turbo link

# 之后所有构建都会使用远程缓存
turbo run build

# 确保已构建依赖的包
pnpm --filter @my-monorepo/shared build

# 重新安装依赖
pnpm install

{
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts"
    }
  }
}

# 清理本地缓存
rm -rf .turbo

# 强制重新构建（忽略缓存）
turbo run build --force

# 清理所有缓存和输出
turbo run clean
pnpm clean

# 查看缓存命中情况
turbo run build --summarize

# 生成缓存摘要文件
turbo run build --summarize=summary.json

# 查看为什么任务被执行（未命中缓存）
turbo run build --dry-run

# 自动迁移配置
npx @turbo/codemod migrate

# 检查迁移后的配置
cat turbo.json

# 验证配置正确性
turbo run build --dry-run

{
  "dependencies": {
    "@my-monorepo/shared": "workspace:*"  // 开发时
  }
}

// 发布后自动转换为：
{
  "dependencies": {
    "@my-monorepo/shared": "1.0.0"  // 发布后
  }
}

{
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  }
}

# 删除 lock 文件
rm pnpm-lock.yaml

# 重新生成
pnpm install

// packages/config/eslint-config/index.js
module.exports = {
  extends: ["eslint:recommended"],
  rules: {
    // 共享规则
  },
};

{
  "eslintConfig": {
    "extends": "@my-monorepo/config/eslint-config"
  }
}

// packages/scripts/src/build.ts
export function build() {
  console.log("Custom build script");
  // 自定义构建逻辑
}

# 登录 Vercel
npx turbo login

# 链接项目
npx turbo link