@icebreakers/monorepo-templates 0.0.0

package/templates/vitepress/tools/turborepo.md

@@ -0,0 +1,149 @@
+# Turborepo
+
+## 1. 什么是 Turborepo？
+
+**Turborepo** 是由 **Vercel** 推出的一个 **高性能 JavaScript/TypeScript monorepo 构建系统**。
+
+它的定位类似于 **NX / Bazel**，但更轻量、更贴合前端生态。
+主要解决 **monorepo（多包/多项目仓库）** 下的构建、缓存和任务调度问题。
+
+👉 通俗说：
+在一个仓库里有多个应用和包，**Turborepo 可以帮你高效管理它们的依赖、构建、测试和发布**。
+
+## 2. Turborepo 有什么用？
+
+### 🚀 性能优化
+
+- **增量构建**：只重新构建改动过的包，而不是全量重建。
+- **智能缓存**：构建结果会缓存，本地和 CI/CD 环境可以共享（比如用远程缓存）。
+- **任务并行化**：最大化利用 CPU 核心，减少构建时间。
+
+### 📦 Monorepo 管理
+
+- 可以在一个仓库中维护多个项目（比如 `templates/` 下是模板，`packages/` 下是共享组件或工具）。
+- 内置工作区（workspace）支持，自动管理依赖关系。
+
+### 🛠 灵活的任务编排
+
+- 你可以定义 `build`、`test`、`lint` 等任务，Turborepo 会根据依赖关系和缓存情况决定执行策略。
+
+### 🌍 和 Vercel 深度集成
+
+- 在 Vercel 平台上可以直接利用远程缓存，加速 CI/CD。
+
+## 3. Turborepo 怎么用？
+
+### 安装
+
+全局安装（可选）：
+
+```bash
+npm install turbo --global
+```
+
+在项目中初始化：
+
+```bash
+npx create-turbo@latest
+```
+
+这会生成一个 monorepo 结构，比如：
+
+```
+.
+├── apps
+│   ├── web     # 前端应用
+│   └── docs    # 文档应用
+└── packages
+    ├── ui      # UI 组件库
+    └── config  # 配置共享包
+```
+
+### 配置 `turbo.json`
+
+核心配置文件，放在仓库根目录：
+
+```json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"]
+    },
+    "lint": {},
+    "test": {
+      "dependsOn": ["build"]
+    }
+  }
+}
+```
+
+解释：
+
+- `build` 任务依赖于上游包的 `build`。
+- 缓存 `dist/**` 或 `.next/**` 输出目录。
+- `test` 依赖于 `build`。
+
+### 运行命令
+
+在根目录执行：
+
+```bash
+turbo run build
+```
+
+👉 Turborepo 会：
+
+- 找到所有定义了 `build` 脚本的项目。
+- 根据依赖关系决定执行顺序。
+- 如果缓存可用，直接跳过执行，秒完成。
+
+同理：
+
+```bash
+turbo run lint
+turbo run test
+```
+
+### 远程缓存（可选）
+
+如果团队协作或 CI/CD，需要共享缓存：
+
+```bash
+npx turbo login
+npx turbo link
+```
+
+这样不同开发者、CI 都可以复用缓存，进一步加速。
+
+## 4. 总结
+
+- **Turborepo = 高性能 monorepo 构建工具**。
+- **核心优势**：缓存、增量构建、并行执行、依赖感知。
+- **适用场景**：
+  - 大型 monorepo（多个应用 + 包）。
+  - 需要快速构建和测试的团队。
+  - 想用 Vercel 部署的项目。
+
+好的 👍，我来帮你把 **Turborepo、Lerna、Nx** 三个常见 **Monorepo 管理工具**做一个对比表。
+
+## Turborepo vs Lerna vs Nx
+
+| 特性 / 工具       | **Turborepo**                            | **Lerna**                                   | **Nx**                                          |
+| ----------------- | ---------------------------------------- | ------------------------------------------- | ----------------------------------------------- |
+| **定位**          | 高性能构建系统，专注缓存、并行和增量构建 | 最早的 JS monorepo 工具，专注版本管理和发布 | 企业级开发平台，集成构建、测试、代码生成等功能  |
+| **核心优势**      | ⚡ 高速缓存（本地 & 远程）、并行任务执行 | 📦 包版本管理（独立/统一模式）、发布到 npm  | 🛠 丰富的插件生态、代码生成器、强大的依赖图分析 |
+| **依赖管理**      | 基于 pnpm/yarn/npm workspaces            | 基于 npm/yarn workspaces                    | 内置强依赖图（project graph）管理               |
+| **构建/缓存机制** | ✅ 智能缓存 & 增量构建                   | ❌ 无缓存机制                               | ✅ 强大缓存 & 增量构建（类似 Bazel）            |
+| **任务编排**      | pipeline 模式（`turbo.json`）            | 简单顺序执行                                | 高度可配置任务调度器（依赖感知）                |
+| **语言支持**      | 主要是 JS/TS 生态                        | 主要是 JS/TS 生态                           | 多语言支持（JS/TS/Go/Rust/Python 等）           |
+| **学习成本**      | ⭐⭐ 低（配置简洁，前端友好）            | ⭐⭐ 低（老牌工具，功能单一）               | ⭐⭐⭐ 高（功能多，配置复杂）                   |
+| **社区活跃度**    | 🚀 高（Vercel 维护，发展迅速）           | ⚠️ 中等（已过巅峰，更多用于发布流程）       | 🚀 高（企业应用广泛，社区和插件丰富）           |
+| **适合场景**      | 前端/全栈项目，追求构建速度 & CI/CD 效率 | 多包库发布（如 npm 包集合项目）             | 大型企业级 monorepo，跨语言/跨团队复杂项目      |
+
+## 对比总结
+
+- **Turborepo**：主打 **快**，缓存和增量构建体验非常好，适合前端/全栈团队。
+- **Lerna**：更像是 **版本管理/发包工具**，现在多和 pnpm/Yarn Workspaces 搭配，用于管理 npm 包版本和发布。
+- **Nx**：功能最全，适合大型团队，有可视化依赖图、代码生成、跨语言支持，但学习曲线较陡。

package/templates/vitepress/why/assets/npm-dt.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 23.1.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 256 256" style="enable-background:new 0 0 256 256;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#3178C6;}
+	.st1{fill:#FFFFFF;}
+</style>
+<rect class="st0" width="256" height="256"/>
+<rect x="6" y="6" class="st1" width="244" height="244"/>
+<path class="st0" d="M41.8,111.5c8.6-1.6,19.9-2.5,31.8-2.5c19.7,0,32.6,4.2,42.6,13c10.8,9.4,17.6,24.5,17.6,46
+	c0,23.4-7.3,39.5-17.3,49.5c-11,10.7-27.6,15.8-48,15.8c-12.2,0-20.8-0.9-26.7-1.8V111.5z M65.4,211.2c2,0.5,5.2,0.5,8.2,0.5
+	c21.3,0.2,35.2-13.6,35.2-42.7c0.2-25.4-12.5-38.8-32.7-38.8c-5.2,0-8.6,0.5-10.6,1.1V211.2z"/>
+<path class="st0" d="M169.4,134.7h-32.2v-22.8h92.3v22.8h-32.8V232h-27.3V134.7z"/>
+</svg>

package/templates/vitepress/why/assets/npm-ts.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 23.1.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 viewBox="0 0 256 256" style="enable-background:new 0 0 256 256;" xml:space="preserve">
+<style type="text/css">
+	.st0{fill:#3178C6;}
+	.st1{fill-rule:evenodd;clip-rule:evenodd;fill:#FFFFFF;}
+</style>
+<rect class="st0" width="256" height="256"/>
+<path class="st1" d="M150.5,200.5v27.6c4.5,2.3,9.8,4,15.9,5.2s12.6,1.7,19.4,1.7c6.6,0,12.9-0.6,18.9-1.9s11.2-3.4,15.7-6.3
+	c4.5-2.9,8-6.7,10.7-11.4c2.6-4.7,3.9-10.5,3.9-17.4c0-5-0.7-9.4-2.2-13.2s-3.7-7.1-6.5-10.1c-2.8-2.9-6.2-5.6-10.1-7.9
+	c-3.9-2.3-8.4-4.5-13.3-6.6c-3.6-1.5-6.9-2.9-9.8-4.4c-2.9-1.4-5.3-2.8-7.3-4.3c-2-1.5-3.6-3-4.7-4.7s-1.6-3.5-1.6-5.6
+	c0-1.9,0.5-3.6,1.5-5.1s2.4-2.8,4.1-3.9c1.8-1.1,4-1.9,6.6-2.5c2.6-0.6,5.5-0.9,8.6-0.9c2.3,0,4.7,0.2,7.3,0.5
+	c2.6,0.3,5.1,0.9,7.7,1.6c2.6,0.7,5.1,1.6,7.6,2.7c2.4,1.1,4.7,2.4,6.8,3.8v-25.8c-4.2-1.6-8.8-2.8-13.8-3.6s-10.7-1.2-17.1-1.2
+	c-6.6,0-12.8,0.7-18.7,2.1c-5.9,1.4-11,3.6-15.5,6.6c-4.5,3-8,6.8-10.6,11.4c-2.6,4.6-3.9,10.2-3.9,16.6c0,8.2,2.4,15.2,7.1,21.1
+	c4.8,5.8,12,10.7,21.6,14.8c3.8,1.6,7.3,3.1,10.6,4.6c3.3,1.5,6.1,3,8.5,4.7s4.3,3.4,5.7,5.3s2.1,4.1,2.1,6.5c0,1.8-0.4,3.4-1.3,5
+	c-0.9,1.5-2.2,2.8-3.9,4s-3.9,2-6.6,2.6s-5.7,0.9-9.2,0.9c-6,0-11.9-1.1-17.8-3.2C161,207.8,155.5,204.7,150.5,200.5L150.5,200.5z
+	 M104.5,131.7H140V109H41v22.7h35.3V233h28.1V131.7z"/>
+</svg>

package/templates/vitepress/why/examples/0.npm-basic-package/index.js

@@ -0,0 +1,10 @@
+/* eslint-disable no-console */
+console.log(`load ${__filename}`)
+
+function sayHello() {
+  console.log('hello world')
+}
+
+module.exports = {
+  sayHello,
+}

package/templates/vitepress/why/examples/0.npm-basic-package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "icebreaker-npm-basic-package",
+  "version": "1.0.0",
+  "description": "",
+  "author": "",
+  "license": "ISC",
+  "main": "index.js",
+  "scripts": {
+    "start": "node ."
+  }
+}

package/templates/vitepress/why/examples/1.npm-basic-package/index.cjs

@@ -0,0 +1,12 @@
+/* eslint-disable no-console */
+console.log(`cjs load ${__filename}`)
+
+function sayHello() {
+  const message = 'hello world cjs'
+  console.log(message)
+  return message
+}
+
+module.exports = {
+  sayHello,
+}

package/templates/vitepress/why/examples/1.npm-basic-package/index.d.ts

@@ -0,0 +1 @@
+export const sayHello: () => string

package/templates/vitepress/why/examples/1.npm-basic-package/index.js

@@ -0,0 +1,8 @@
+/* eslint-disable no-console */
+console.log(`esm load ${import.meta.filename}`)
+
+export function sayHello() {
+  const message = 'hello world esm'
+  console.log(message)
+  return message
+}

package/templates/vitepress/why/examples/1.npm-basic-package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "icebreaker-npm-basic-package-multiple-exports",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "",
+  "author": "",
+  "license": "ISC",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  },
+  "scripts": {
+    "start:cjs": "node ./index.cjs",
+    "start:esm": "node ./index.js"
+  }
+}

package/templates/vitepress/why/examples/2.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://monorepo.icebreaker.top/

package/templates/vitepress/why/examples/2.npm-basic-package/package-lock.json

@@ -0,0 +1,30 @@
+{
+  "name": "icebreaker-npm-basic-package",
+  "version": "1.0.2",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "icebreaker-npm-basic-package",
+      "version": "1.0.2",
+      "license": "ISC",
+      "devDependencies": {
+        "typescript": "^5.8.3"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.8.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz",
+      "integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}

package/templates/vitepress/why/examples/2.npm-basic-package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "icebreaker-npm-basic-package",
+  "type": "module",
+  "version": "1.0.5",
+  "description": "",
+  "author": "",
+  "license": "ISC",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build:cjs": "tsc --project tsconfig.cjs.json && node rename-ext.js dist/cjs .js .cjs && node rename-ext.js dist/cjs .js.map .cjs.map",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build": "npm run build:cjs && npm run build:esm",
+    "_debug:cjs": "node dist/cjs/index.js",
+    "debug:esm": "node dist/esm/index.js",
+    "debug": "tsx src/index.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/vitepress/why/examples/2.npm-basic-package/rename-ext.js

@@ -0,0 +1,24 @@
+// rename-ext.js
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const [dir, fromExt, toExt] = process.argv.slice(2)
+
+function renameFilesRecursively(currentPath) {
+  const entries = fs.readdirSync(currentPath, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = path.join(currentPath, entry.name)
+
+    if (entry.isDirectory()) {
+      renameFilesRecursively(fullPath)
+    }
+    else if (entry.isFile() && entry.name.endsWith(fromExt)) {
+      const newPath = fullPath.slice(0, -fromExt.length) + toExt
+      fs.renameSync(fullPath, newPath)
+    }
+  }
+}
+
+renameFilesRecursively(dir)

package/templates/vitepress/why/examples/2.npm-basic-package/src/index.ts

@@ -0,0 +1,8 @@
+/* eslint-disable no-console */
+export function sayHello() {
+  const message = 'hello world typescript'
+  console.log(message)
+  return message
+}
+
+console.log(`load package icebreaker-npm-basic-package`)

package/templates/vitepress/why/examples/2.npm-basic-package/tsconfig.cjs.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node10",
+    "outDir": "./dist/cjs"
+  }
+}

package/templates/vitepress/why/examples/2.npm-basic-package/tsconfig.esm.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "outDir": "./dist/esm"
+  }
+}

package/templates/vitepress/why/examples/2.npm-basic-package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "rootDir": "./src",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist", // 具体格式的 tsconfig 会覆盖
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/vitepress/why/examples/3.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://monorepo.icebreaker.top/

package/templates/vitepress/why/examples/3.npm-basic-package/build.config.ts

@@ -0,0 +1,24 @@
+import path from 'node:path'
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  // entries: ['./src/index', './src/cli'],
+  rollup: {
+    // 内联，相当于 nodeResolve
+    inlineDependencies: true,
+    // cjs
+    emitCJS: true,
+    // 添加 cjs 注入
+    cjsBridge: true,
+    dts: {
+      // https://github.com/unjs/unbuild/issues/135
+      respectExternal: false,
+    },
+  },
+  alias: {
+    // 别名
+    '@': path.resolve(__dirname, './src'),
+  },
+  // dts
+  declaration: true,
+})