@icebreakers/monorepo 1.2.3 → 2.0.0

package/dist/index.js

@@ -1,34 +1,62 @@
 import {
   GitClient,
+  assetsDir,
   cleanProjects,
+  createContext,
   createNewProject,
+  defineMonorepoConfig,
   escapeStringRegexp,
+  getCreateChoices,
   getFileHash,
+  getTemplateMap,
   getWorkspaceData,
   getWorkspacePackages,
   init,
   init_esm_shims,
   isFileChanged,
   isMatch,
+  loadMonorepoConfig,
+  logger,
+  name,
+  packageDir,
+  resolveCommandConfig,
+  rootDir,
   setVscodeBinaryMirror,
   syncNpmMirror,
-  upgradeMonorepo
-} from "./chunk-4NCVGJER.js";
+  templateMap,
+  templatesDir,
+  upgradeMonorepo,
+  version
+} from "./chunk-JJQVR3B4.js";
 
 // src/index.ts
 init_esm_shims();
 export {
   GitClient,
+  assetsDir,
   cleanProjects,
+  createContext,
   createNewProject,
+  defineMonorepoConfig,
   escapeStringRegexp,
+  getCreateChoices,
   getFileHash,
+  getTemplateMap,
   getWorkspaceData,
   getWorkspacePackages,
   init,
   isFileChanged,
   isMatch,
+  loadMonorepoConfig,
+  logger,
+  name,
+  packageDir,
+  resolveCommandConfig,
+  rootDir,
   setVscodeBinaryMirror,
   syncNpmMirror,
-  upgradeMonorepo
+  templateMap,
+  templatesDir,
+  upgradeMonorepo,
+  version
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@icebreakers/monorepo",
   "type": "module",
-  "version": "1.2.3",
+  "version": "2.0.0",
   "description": "The icebreaker's monorepo manager",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -42,8 +42,9 @@
     "@pnpm/logger": "^1001.0.0",
     "@pnpm/types": "^1000.8.0",
     "@pnpm/worker": "^1000.1.13",
-    "@pnpm/workspace.find-packages": "^1000.0.37",
+    "@pnpm/workspace.find-packages": "^1000.0.38",
     "@pnpm/workspace.read-manifest": "^1000.2.4",
+    "c12": "^3.3.0",
     "commander": "^14.0.1",
     "comment-json": "^4.2.5",
     "consola": "^3.4.2",

package/templates/apps/client/package.json

@@ -6,6 +6,8 @@
   "scripts": {
     "dev": "vite",
     "build": "vue-tsc -b && vite build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "preview": "vite preview",
     "deploy": "wrangler deploy",
     "cf-typegen": "wrangler types",
@@ -13,21 +15,21 @@
   },
   "dependencies": {
     "@faker-js/faker": "^10.0.0",
-    "@tanstack/vue-query": "^5.89.0",
+    "@tanstack/vue-query": "^5.90.2",
     "@tanstack/vue-table": "^8.21.3",
     "@tanstack/vue-virtual": "^3.13.12",
-    "@trpc/client": "^11.5.1",
+    "@trpc/client": "^11.6.0",
     "pinia": "^3.0.3",
-    "vue": "^3.5.21",
+    "vue": "^3.5.22",
     "vue-i18n": "^11.1.12",
     "vue-router": "^4.5.1"
   },
   "devDependencies": {
-    "@cloudflare/vite-plugin": "^1.13.3",
-    "@hono/node-server": "^1.19.3",
+    "@cloudflare/vite-plugin": "^1.13.7",
+    "@hono/node-server": "^1.19.4",
     "@hono/trpc-server": "^0.4.0",
     "@tailwindcss/vite": "^4.1.13",
-    "@trpc/server": "^11.5.1",
+    "@trpc/server": "^11.6.0",
     "@vitejs/plugin-vue": "^6.0.1",
     "@vitejs/plugin-vue-jsx": "^5.1.1",
     "@vue/tsconfig": "^0.8.1",
@@ -35,11 +37,11 @@
     "tailwindcss": "^4.1.13",
     "typescript": "~5.9.2",
     "unplugin-vue-router": "^0.15.0",
-    "vite": "^7.1.6",
+    "vite": "^7.1.7",
     "vite-plugin-vue-devtools": "^8.0.2",
     "vite-tsconfig-paths": "^5.1.4",
-    "vue-tsc": "3.0.7",
-    "wrangler": "^4.38.0",
+    "vue-tsc": "3.0.8",
+    "wrangler": "^4.40.2",
     "zod": "^4.1.11"
   }
 }

package/templates/apps/client/wrangler.jsonc

@@ -1,7 +1,7 @@
 {
   "$schema": "./node_modules/wrangler/config-schema.json",
   "name": "monorepo-client",
-  "compatibility_date": "2025-09-21",
+  "compatibility_date": "2025-09-17",
   "main": "./worker/fetch-entry.ts",
   "assets": {
     "not_found_handling": "single-page-application"

package/templates/apps/server/package.json

@@ -51,9 +51,9 @@
     "types": "./dist/index.d.ts"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.3",
+    "@hono/node-server": "^1.19.4",
     "hono": "^4.9.8",
-    "wrangler": "^4.38.0",
+    "wrangler": "^4.40.2",
     "zod": "^4.1.11"
   }
 }

package/templates/apps/website/index.md

@@ -4,148 +4,110 @@ layout: doc
 
 # icebreaker's monorepo 模板
 
-## 功能特性
+整套模板围绕 **pnpm + Turborepo + TypeScript** 打造，帮助团队快速落地一个可维护、可编排、可持续迭代的 `monorepo` 工程。这里我们把使用方式拆成几个核心模块，方便你按需查阅。
 
-- 强大的 `monorepo` 管理 (`pnpm` + `turborepo`)
-- 单元测试框架集成 (`vitest`)
-- 全部都是 `typescript`, 包括 `应用` `类库` 与 `cli` 工具
-- 代码规范与质量 (`eslint` + `@icebreakers/eslint-config` + `@icebreakers/stylelint-config`)
-- `git` 提交规范 (`husky` + `commitlint` + `lint-staged`)
-- `pnpm` `Dockerfile` 部署模板
-- `Github Action` 自动发布 `npm`, `github release` 包 (`changeset`)
-- 配置文件同步升级 `npx @icebreakers/monorepo@latest`
+## 核心能力
+
+- **工作区管理**：`pnpm` workspace + Turborepo 任务编排，内置缓存和过滤能力。
+- **全链路 TypeScript**：所有模板（应用、类库、CLI）均使用 TS，并自带基础测试脚手架（`vitest`）。
+- **质量与规范**：集成 `eslint`、`stylelint`、`husky`、`commitlint`、`lint-staged`，开箱即用。
+- **自动化发布**：`changesets` + GitHub Actions + Dockerfile 模板，实现语义化发版和部署。
+- **命令行助手**：`@icebreakers/monorepo` CLI 提供创建、同步、升级、镜像等常用命令，可通过 `monorepo.config.ts` 自定义行为。
 
-## 如何使用？
+## 快速上手
 
-首先，访问本模板的 [Github 地址](https://github.com/sonofmagic/monorepo-template)，然后按照一下条件:
+1. **拉取模板**：[GitHub](https://github.com/sonofmagic/monorepo-template) 右上角 `Use this template`，或克隆源码。
+2. **安装依赖**：在 `pnpm-workspace.yaml` 所在目录执行 `pnpm install`（需要 Node.js ≥ 20，推荐 `npm i -g pnpm`）。
+3. **可选清理**：运行 `pnpm script:clean` 移除演示包，仅保留最小打包模板；随后再次执行 `pnpm install` 更新 lockfile。
+4. **初始化元数据**：`pnpm script:init` 会批量更新 `package.json`、`README.md` 等公共信息。
 
-- 有 `Github` 账号的，可以登录后，点击右上角的 `Use this template` 按钮
+## 仓库结构速览
 
-- 没有 `Github` 账号的，可以点击 `Code` 按钮，把这个仓库的源码，或 `clone` 或下载到本地
+| 目录                        | 描述                             |
+| --------------------------- | -------------------------------- |
+| `apps/cli`                  | TypeScript 编写的 CLI 模板       |
+| `apps/client`               | Vue 3 + Vite 客户端示例          |
+| `apps/server`               | 基于 Hono 的服务端模板           |
+| `apps/website`              | VitePress 文档站（即本网站源码） |
+| `packages/tsup-template`    | 使用 `tsup` 打包的库模板         |
+| `packages/unbuild-template` | 使用 `unbuild` 打包的库模板      |
+| `packages/vue-lib-template` | Vue 组件库模板                   |
+| `packages/monorepo`         | CLI 及配置同步工具，支持独立升级 |
 
-然后在根目录 (`pnpm-workspace.yaml` 所在的位置) 执行 `pnpm i` 去安装依赖
+## 常用脚本
 
-> 要求 `Nodejs` >= 20，没有 `pnpm` 的，可以使用 `npm i -g pnpm` 来进行安装。
->
-> 什么! 你不会连 [`Nodejs`](https://nodejs.org/en) 还没安装吧？
+| 命令                 | 说明                                                |
+| -------------------- | --------------------------------------------------- |
+| `pnpm script:clean`  | 清理演示仓库，保留最小模板                          |
+| `pnpm script:init`   | 同步初始化 `package.json`、`README.md` 等基础信息   |
+| `pnpm script:sync`   | 使用 `cnpm` 同步所有包到 npmmirror（需预装 `cnpm`） |
+| `pnpm script:mirror` | 为 VS Code 终端写入国内镜像环境变量                 |
 
-## 使用步骤
+更多脚本可在根目录 `package.json` 中查看，命令介绍详见 [工具区](./tools/turborepo.md)。
 
-### 1. 清除不必要的代码
+## CLI 命令概览
 
-执行 `pnpm script:clean` 命令，可以删去大部分的初始 `repo`，只保留一个 `@icebreakers/unbuild-template` 项目作为发包打包模板。
+```bash
+npx monorepo new           # 创建子包/应用
+npx monorepo clean         # 批量删除已勾选的子项目
+npx monorepo sync          # 同步所有包到 npmmirror
+npx monorepo mirror        # 写入 VS Code 镜像配置
+npx monorepo up            # 从最新模板同步配置文件
+```
 
-`clean` 命令执行完成之后，再去执行 `pnpm i` 来更新 `pnpm-lock.yaml`, 并提交 `pnpm-lock.yaml` 文件来锁定 `npm` 包的版本。
+所有命令都支持在 `monorepo.config.ts` 中覆写默认行为，例如新增模板、修改同步命令、跳过 README 初始化等。配置示例见下文和 [配置中心说明](./monorepo/manage.md#使用-monorepo-configts-定制命令行为)。
 
-### 2. 初始化文件
+## 自定义配置：`monorepo.config.ts`
 
-执行 `pnpm script:init` 命令，这个命令会批量修改你关联的配置文件，并生成一份新的 `README.md`
+```ts
+import { defineMonorepoConfig } from '@icebreakers/monorepo'
 
-## 模板包介绍
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'cli',
+      renameJson: true,
+    },
+    clean: {
+      autoConfirm: true,
+      ignorePackages: ['docs'],
+    },
+    upgrade: {
+      skipOverwrite: true,
+      targets: ['.github', 'monorepo.config.ts'],
+    },
+  },
+})
+```
 
-默认模板被放在根目录的 `packages` 和 `apps` 这 `2` 个目录里面
+更多可配置项详见 [管理指南](./monorepo/manage.md)。
 
-### packages 目录
+## 依赖与版本升级
 
-- `@icebreakers/tsup-template` - [`tsup`](https://www.npmjs.com/package/tsup) 打包的库模板
-- `@icebreakers/unbuild-template` - [`unbuild`](https://www.npmjs.com/package/unbuild) 打包的库模板
-- `@icebreakers/monorepo` - 本仓库的更新配置服务，可直接根目录执行 `npx @icebreakers/monorepo@latest` 执行远端 `cli` 命令，进行项目依赖升级同步
-- `@icebreakers/vue-lib-template` - [`vue3`](https://vuejs.org/) 组件库模板，使用 `vite` 打包
+```bash
+pnpm up -rLi
+```
 
-### apps 目录
+- `-r`：递归遍历所有 workspace
+- `-L`：升级到最新版本
+- `-i`：交互式选择（推荐查看差异后再确认）
 
-- `@icebreakers/cli` - 使用 `typescript` 编写的 `cli` 程序模板
-- `@icebreakers/website` - 文档网站模板，使用 `vitepress` 搭建，也是 [monorepo.icebreaker.top](https://monorepo.icebreaker.top/) 的源代码
-- `@icebreakers/server` - 使用 `hono` 搭建的服务端模板，使用 `typescript` 编写
-- `@icebreakers/client` - `vue` 客户端模板
+## 自动化发布
 
-## 更新包的依赖
+模板默认集成 [`changesets`](https://github.com/changesets/changesets) 与推荐的 GitHub Actions 工作流：
 
-在根目录中执行 `pnpm up -rLi` 来进行包的交互式更新，下面是解释:
+1. 安装 [changeset-bot](https://github.com/apps/changeset-bot)。
+2. 在仓库设置中开启 `Actions` 的 `Read and write permissions` 并勾选允许创建 PR。
+3. 在 `Repository secrets` 中配置 `NPM_TOKEN`（若需要 Codecov 也可配置 `CODECOV_TOKEN`）。
+4. 运行 `pnpm changeset`、`pnpm changeset version`、`pnpm changeset publish` 完成发布；或交由 CI 自动执行。
 
-- `-r` : `recursive` 递归选中所有 `repo`
-- `-L` : `latest` 更新到最新
-- `-i` : `interactive` 交互式
+具体操作指南参见 [发包流程](./monorepo/publish.md)。
 
-## 配置自动发包
+## 更多资源
 
-本项目使用 [changesets](https://github.com/changesets/changesets) 进行包的发布和 `changelog` 的生成
-
-> [changesets](https://github.com/changesets/changesets) 的具体使用方式见它的文档
-
-在使用的时候，首先你需要做一些配置：
-
-1. 首先你需要安装 `Github App`: [changeset-bot](https://github.com/apps/changeset-bot)
-
-2. 然后，来到你复制这个模板仓库(`repo`), 上方里的 `Settings` Tab 页面，进行 2 个操作:
-
-### 1. 在 Github 进行 PR 和发包
-
-选择 `Code and automation` > `Actions` > `General`
-
-然后在右侧 `Workflow permissions` 下方选择: `Read and write permissions`
-
-然后选中 `Allow GitHub Actions to create and approve pull requests`
-
-最后，点击下方的保存按钮即可。
-
-这样 `changeset` 就有权限对你进行 `PR` 和代码版本更新了！
-
-### 2. 在 npm 发包
-
-选择 `Security` > `Secrets and variables` > `Actions`
-
-然后在右侧的 `Repository secrets` 设置你的 `NPM_TOKEN` 这个可以在你的 `npmjs.com` 账号中生成获取
-
-(假如你需要单元测试代码覆盖率，你需要设置 `CODECOV_TOKEN`)
-
-## eslint + stylelint 校验
-
-引用到的规则参考 `https://eslint.icebreaker.top/`
-
-[Github 地址](https://github.com/sonofmagic/eslint-config)
-
-## 内置脚本
-
-- `pnpm script:clean` 删去大部分的初始`repo`，只保留一个 `@icebreakers/bar` 项目作为发包打包模板
-- `pnpm script:init` 初始化一些 `package.json` 里的字段
-- `pnpm script:sync` 使用 `cnpm sync` 功能，把本地所有的包，同步到 [`npmmirror`](https://www.npmmirror.com/) 上，需要安装 `cnpm`
-- `pnpm script:mirror` 使用 `cnpm` binary mirror 功能，使用国内二进制下载地址 (使用 vscode 环境变量)
-
-## 创建新的项目
-
-在 `monorepo` 的任意位置，打开命令行，然后执行 `npx monorepo new` 即可进入交互模式创建一个空的类库，
-
-可通过传入 **可选**参数 `path` 进行修改, 比如 `npx monorepo new [path]`, 此时的目录就从 `foo` 变为了 `[path]`
-
-> 命令 `new` 的别名为 `create`, 也可以使用 `npx monorepo create` 来创建新的项目
-
-## 配置同步方式
-
-更新 `@icebreakers/monorepo` 到最新版本，然后
-
-在根目录下执行: `npx monorepo up`
-
-> 假如你想直接从远端获取，可以 `npx @icebreakers/monorepo@latest up`
-
-这个命令会把所有的文件从最新版本，对你本地进行覆盖，你可以从 `git` 暂存区把你不想要的文件剔除
-
-### 参数
-
-`npx monorepo up --raw`
-
-这个命令会从全部文件中去除 `Github` 相关的文件
-
-`npx monorepo up -i`
-
-这个命令会进行命令行选择模式，你可以在这里对想要复制的文件进行筛选
-
-`npx monorepo up -s`
-
-跳过文件的新增，只保留文件的修改
-
----
-
-当然你可以同时使用这多个命令
-
-`npx monorepo up -i --raw`
+- [为什么选择 monorepo？](./monorepo/index.md)
+- [pnpm workspaces 与 Turborepo 组合的优势](./monorepo/manage.md)
+- [工具链介绍](./tools/turborepo.md)
+- [常见思考与 FAQ](./thinking.md)
+
+> 欢迎结合自己的业务场景对模板做进一步裁剪与扩展，建议在自定义后保留 `monorepo.config.ts` 以便集中管理命令默认值。

package/templates/apps/website/monorepo/index.md

@@ -1,68 +1,46 @@
-# 为什么往 monorepo 方向演进
+# 为什么选择 Monorepo？
 
-Node.js 项目的 Git 仓库越来越倾向于采用 **Monorepo（单一代码库）** 的架构，主要原因是 **项目复杂度增加** 和 **团队协作需求提升**。
+随着项目复杂度提升，Node.js 团队越来越倾向于把多套服务、组件库、CLI 工具放在同一个仓库里。Monorepo 的核心价值在于 **集中管理依赖与流程**，从而让重构、协作、发布都更高效。
 
-往 monorepo 方向演进的核心在于，它能够让我们，更好的做代码拆分和依赖关系的管理
+## Monorepo 的主要收益
 
-## 集中管理多个模块的优势
+| 维度     | 收益                                                               |
+| -------- | ------------------------------------------------------------------ |
+| 依赖管理 | `pnpm` 等工具会共享缓存、避免重复安装；严格依赖隔离杜绝“幽灵依赖”  |
+| 构建效率 | 借助 Turborepo 的缓存与依赖图，仅构建真正改动的包，CI 时间显著降低 |
+| 原子提交 | 一个提交即可跨多个模块同步改动，便于回滚与审计                     |
+| 协作体验 | 同一仓库统一配置、脚本与规范，减少跨项目跳转和环境差异             |
+| 可复用性 | 公共库、UI 组件、工具函数在 workspace 内即可本地引用并共享         |
 
-现代 Node.js 项目通常不再是单体应用，而是由多个模块、服务、包组成，例如：
+## 与 Polyrepo 的对比
 
-- 多个 npm 包（如 utils、core、api、cli）
-- 多个微服务（如 auth-service、user-service）
-- Web 与后端共存（如 frontend + backend）
+| Polyrepo 常见痛点                | Monorepo 的解决方式                                |
+| -------------------------------- | -------------------------------------------------- |
+| 每个仓库单独装依赖、重复维护脚本 | Workspace 共享依赖与脚本，一次配置多处使用         |
+| 同步多个仓库中的接口或配置       | 原子提交 + Turborepo 构建，修改一次即可全仓库生效  |
+| CI/CD 配置分散、发布流程冗长     | 基于 changesets 和统一仓库配置快速搭建自动化流水线 |
+| 大规模重构成本高                 | 搜索范围集中，易于批量修改、验证与回滚             |
 
-**Monorepo 优点：**
+## 常见落地场景
 
-| 特性                   | 说明                                                      |
-| ---------------------- | --------------------------------------------------------- |
-| **统一依赖管理**       | 所有模块共享依赖，减少版本冲突和冗余安装                  |
-| **统一构建与发布流程** | 可以使用工具（如 TurboRepo、Nx、Lerna）管理构建/测试/发布 |
-| **原子性提交**         | 一个提交可以跨多个模块进行变更，方便追踪问题              |
-| **简化跨模块协作**     | 不需要在不同仓库之间切换和发布，仅通过本地引用即可调试    |
+- **多端同仓**：Web、Server、CLI 共存，代码共享严格受控。
+- **组件库/工具链**：公共 API 与内部应用一起维护，避免版本漂移。
+- **微服务集成**：多个服务共享协议、类型定义，发布与部署流程统一。
+- **巨石拆分**：将原有大型项目拆成多个 package，逐步抽象并复用。
 
-## 适配现代工具链的需求
+## 迁移建议
 
-Monorepo 的流行也和一些工具链的成熟有关：
+1. **先集中依赖**：把最常见的公共依赖和脚本统一到根目录，利用 `pnpm workspace` 管理版本。
+2. **逐步迁移模块**：按照业务领域或团队边界迁移子模块，保留原 CI 作为兜底。
+3. **引入构建缓存**：配置 Turborepo，使用 `turbo run <task> --filter=<scope>` 控制任务范围。
+4. **接入 changesets**：在迁移过程中就开始记录版本与变更，养成可发布的节奏。
+5. **通过 monorepo.config.ts 定制命令**：按团队习惯调整 `create` 模板、`clean` 行为、`upgrade` 目标等，提高可维护性。
 
-- **Lerna** / **Nx** / **Turborepo**：支持模块依赖分析、并行任务执行、缓存等高级特性
-- **PNPM workspaces** / **Yarn workspaces** / **NPM workspaces**：简化依赖和 workspace 管理
-- **ESBuild、Vite、Babel** 等构建工具对 Monorepo 的支持逐渐增强
+## 进一步阅读
 
-## 对大型团队更友好
+- [仓库管理实践](./manage.md) —— 如何将 pnpm + Turborepo + monorepo.config 协同使用。
+- [发包与变更日志](./publish.md) —— 使用 changesets 管理版本、自动化发布。
+- [工具专题](../tools/turborepo.md) —— 常用工具的配置与技巧。
+- [常见思考](../thinking.md) —— 关于模块拆分、包结构的经验分享。
 
-在大型团队或企业中，Monorepo 可以带来更好的协作体验：
-
-- 易于规范代码风格和测试策略
-- DevOps 部署流程统一（CI/CD 更易维护）
-- 更容易进行全局重构（如重命名公共 API）
-
-## Facebook、Google 等大厂的示范效应
-
-大型公司（如 Google、Facebook、Uber、Airbnb）早期就在使用 Monorepo，逐渐被开源社区效仿：
-
-- React、Angular、NestJS 等大型 Node/TS 项目都采用 Monorepo
-- 社区也贡献了很多相关最佳实践和工具
-
-## 相比 Polyrepo（多个仓库）的问题
-
-| Polyrepo 问题    | 描述                                 |
-| ---------------- | ------------------------------------ |
-| 版本依赖管理复杂 | 多个仓库依赖版本不一致会导致兼容问题 |
-| 跨项目协作成本高 | 修改一个接口需改多个仓库并同步发布   |
-| 重复构建和发布   | 每个项目都要重复设置 CI/CD 流程      |
-| 脚本和工具重复   | 每个仓库需要重复维护脚本、配置等     |
-
-## 非常适合巨石项目拆分
-
-比如一个巨石项目，里面有 `500` 个直接依赖，可以通过把它改造成一个 `monorepo` 的方式，逐步的把依赖和逻辑拆出来，让每个包保持独立的最小化的依赖。
-
-拆分之后，这时候可能父项目最终有 `100` 个直接共享依赖，拆分出 `20` 个子包，每个包里只有 `20` 个依赖了, 这样依赖的可维护性就好很多。
-
-同时这样也方便进行多模块共同开发，和进行单元测试。
-
-假如做个比喻的话，这就像，你把原先拖成一块的项目，拆分成一个一个积木，然后把积木组合起来，这个项目就能跑了。而且其中的任意模块，都是可以单独替换和发包共享的。
-
-## 总结
-
-在项目小的时候，Polyrepo 管理简单清晰，但随着模块增多、团队扩大，**Monorepo 提供了更高效、可维护、标准化的开发体验**，这是它越来越被 Node.js 项目采用的核心原因。
+> Monorepo 不是银弹，但在需要大量复用、自动化、跨团队协作的场景下，它能显著提升工程效率。关键是配合合适的工具与规范，让拆分后的每个模块都有清晰的职责与边界。