@icebreakers/monorepo-templates 0.0.0

package/templates/vitepress/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@icebreakers/website",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "https://monorepo.icebreaker.top source code",
+  "author": "ice breaker <1324318532@qq.com>",
+  "homepage": "https://monorepo.icebreaker.top",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/monorepo-template.git",
+    "directory": "templates/vitepress"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/monorepo-template/issues"
+  },
+  "keywords": [],
+  "scripts": {
+    "dev": "vitepress dev",
+    "build": "vitepress build",
+    "preview": "vitepress preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "vue": "^3.5.26"
+  },
+  "devDependencies": {
+    "@braintree/sanitize-url": "^7.1.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "cytoscape": "^3.33.1",
+    "cytoscape-cose-bilkent": "^4.1.0",
+    "dayjs": "^1.11.19",
+    "debug": "^4.4.3",
+    "mermaid": "^11.12.2",
+    "tailwindcss": "^4.1.18",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-mermaid": "^2.0.17"
+  }
+}

package/templates/vitepress/thinking.md

@@ -0,0 +1,88 @@
+# 我对 monorepo 的一些思考
+
+## 前言
+
+最近在自己的新项目中，我创建并使用了 [monorepo-template](https://github.com/sonofmagic/monorepo-template) 模板，并不断地做了不少改进。
+
+在此，我想借此机会分享一下这个模板的演变过程，以及我对 `monorepo` 的一些思考。
+
+## 它的由来
+
+为了应对越来越多的发包场景，我创建了 [npm-lib-template](https://github.com/sonofmagic/npm-lib-template) 模板
+
+这是一个 `git` 单仓单 `npm` 包模板，使用 `rollup` 进行打包，然后再发布到 `npm` 和 `github`
+
+然而，在后续开发中，我发现单仓库的模式在某些场景下难以应对。
+
+例如，当需要引用其他自己的包，进行单元测试并再次发包时，这时候往往要在多个项目之间进行来回的切换更改，管理复杂度会迅速上升。
+
+`git submodule` 也是另外一条路子，但是我对每次都要同步 `hash` 感到深恶痛绝，遂放弃 (不过某些极其特殊场景的实现，还是只能利用这个功能)。
+
+因此，我决定要创建一个 [monorepo 项目模板](https://github.com/sonofmagic/monorepo-template) ，以应对这些需求。
+
+## 技术选型
+
+### 管理工具
+
+在 `monorepo` 的管理上，我选择了 `pnpm` 和 `turborepo` 这对组合，原因很简单：它们都非常快。
+
+- `pnpm` 又可以节省磁盘空间，又能够链接自特定的内容寻址存储库，是为快也
+- `turborepo` 有构建缓存，是为快也 `too`.
+
+### 语言与打包
+
+我选择使用纯 `TypeScript` 来编写所有类库项目，并使用 `tsup` / `unbuild` 进行打包，默认输出格式为 `cjs` 和 `esm`，并利用 `package.json` 中的 `exports` 字段进行分发。
+
+### 直接调试
+
+在直接调试时，我抛弃了 `dist` + `sourcemap` 的调试方式，使用了 `tsx`，它非常适合调试 `TypeScript` 编写的 `CLI` 项目。
+
+### 测试框架
+
+测试方面，我选择了 `vitest`。
+
+它不仅速度快，还很好地支持 `cjs`、`esm` 和 `TypeScript`，同时也适合 `monorepo` 项目。你可以利用 `turbo` 来执行单个的 `vitest` 任务，也可以利用 `vitest.workspace` 来进行多任务测试。
+
+最初我使用的是 `jest` + `ts-jest`，但它对多格式的混合模块的支持不够理想，最终我选择了 `vitest`。
+
+### 代码规范与质量控制
+
+为了保持代码质量，我使用了 `eslint` 和 `stylelint`，并基于自己的配置包 `@icebreakers/eslint-config` 和 `@icebreakers/stylelint-config` 来进行代码格式化和规范化。
+
+我还为 `.vscode` 配置了一些推荐插件和编辑器选项。
+
+此外，通过 `husky` 添加了 `git hook`，配合 `lint-staged` 对提交的代码进行校验。与 `commitlint` 结合使用，以确保 `git` 提交信息符合规范。
+
+### 本地引用与发包替换
+
+利用 `publishConfig` 会在发包的时候替换 `package.json` 字段的方式，在本地包相互引用的时候，都使用 `Typescript` 源文件的方式导出，在 `publishConfig` 里定义的导出为，真正在不同环境中，指向 `dist` 中不同格式的产物地址。
+
+通过这种方式，可以大大加速整个 `monorepo` 的开发测试速度，避免反复通过 `watch` 来构建 `dist` 和 `sourcemap`，也避免一构建出产物，对应的 `Typescript` 文件，就报错的问题。
+
+### 发包流程
+
+我采用了 `changesets`，它在 `monorepo` 环境下发布非常方便。功能非常的多，具体可以查看官方文档。
+
+### Github 相关配置
+
+在 `.github` 目录下，我提供了默认的 `CI/CD` 流程配置，以及用户提交 `issue` 时的模板。经过少量配置后，就可以实现自动发布 `npm` 包、创建 `git tag` 以及生成 `GitHub release`。
+
+此外，模板里还有许多为 `GitHub` 显示优化的 `md` 文档。
+
+## 部署
+
+文档网站通过 `netlify.toml` 配置部署在 `Netlify` 上。最初我使用的是 `Vercel`，但由于**国内**访问速度的原因，最终迁移到了 `Netlify`。
+
+而且由于我是开源项目贡献者的原因，`Netlify` 为我 `免费` 提供了 `Pro` 版本的计划 (通常这需要 `$19/per member/month`)
+
+感谢 `Netlify`! 爱你❤️😍。
+
+如果看到这里的哥们，你也有一定影响力的开源项目，也可以通过下方的链接申请。
+
+https://www.netlify.com/legal/open-source-policy/
+
+## 总结
+
+从单仓到 `monorepo` 的转变不仅仅是对工具的选择，更是对项目管理模式的优化。通过采用合适的工具链，能够更高效地管理多包项目的同时，利用 `CI/CD` 确保代码的质量和发布的顺畅。
+
+希望这些思考对你有所帮助，也欢迎大家提出各种建议和意见。

package/templates/vitepress/tools/changeset.md

@@ -0,0 +1,87 @@
+# Changesets
+
+[Changesets](https://github.com/changesets/changesets)。它帮助你在 **monorepo** 或多包项目中更有条理地维护变更日志（changelog）、版本号升级策略以及自动化发布流程。
+
+## 1. 什么是 Changeset？
+
+- **核心思想**：每一次改动，不直接修改 `package.json` 里的版本号，而是通过写一个 `changeset` 文件（通常放在 `.changeset` 文件夹下）。
+- **作用**：
+  - 记录每次改动影响了哪些包（哪些需要 bump 版本）。
+  - 指定改动类型（`patch`、`minor`、`major`）。
+  - 自动生成 **Changelog**。
+  - 自动修改 `package.json` 的版本号。
+  - 与 CI/CD 集成后，可以实现一键自动发版。
+
+## 2. 如何使用 Changesets？
+
+### 安装
+
+```bash
+npm install --save-dev @changesets/cli
+```
+
+### 初始化
+
+```bash
+npx changeset init
+```
+
+会生成一个 `.changeset` 文件夹，里面包含配置文件。
+
+### 添加变更
+
+当你完成某个功能或修复后，运行：
+
+```bash
+npx changeset
+```
+
+它会问：
+
+1. 哪些包受影响？
+2. 这是 **patch**（补丁）、**minor**（新功能）、还是 **major**（重大变更）？
+3. 变更的描述是什么？
+
+这会生成一个类似这样的文件：
+
+```yaml
+# .changeset/sweet-pandas-sing.md
+---
+my-package: patch
+---
+
+修复了登录时的 bug
+```
+
+### 应用版本更新
+
+当积累了多个 changeset 后，可以执行：
+
+```bash
+npx changeset version
+```
+
+它会根据 changeset 文件：
+
+- 更新对应包的版本号。
+- 生成/更新 `CHANGELOG.md`。
+
+### 发布
+
+最后可以发布：
+
+```bash
+npx changeset publish
+```
+
+会自动调用 `npm publish`，把包发到 npm registry。
+
+## 3. 在 Monorepo 中的优势
+
+- 避免多人协作时冲突：大家都往 `.changeset` 添加文件，不会直接改 `package.json`。
+- 统一生成 changelog：自动保证每个版本的改动都被记录。
+- 自动化发布：和 GitHub Actions 等 CI 工具结合，可在合并到主分支后自动发版。
+
+## 总结
+
+**Changeset 就是一个版本管理与发版工具**，它通过“先记录再统一处理”的方式，帮助 npm 包（尤其是 monorepo）保持版本升级和 changelog 的一致性与可追溯性。

package/templates/vitepress/tools/husky.md

@@ -0,0 +1,108 @@
+# Husky
+
+## 1. 什么是 Husky？
+
+**Husky** 是一个用于在 **Git hooks**（如 `pre-commit`、`pre-push`、`commit-msg` 等）中运行脚本的工具。
+它的作用是让你在提交代码前或推送代码前，自动执行一些校验、格式化或测试，从而保证代码质量和团队规范。
+
+> 简单来说：**Husky = Git hooks 的管理工具**。
+
+## 2. Husky 有什么用？
+
+常见用途：
+
+1. **代码格式化**
+   在提交前运行 `prettier --write .`，确保代码风格一致。
+2. **Lint 检查**
+   在 `pre-commit` 时执行 `eslint`，防止有 lint 错误的代码被提交。
+3. **运行测试**
+   在 `pre-push` 时执行 `npm test`，防止未通过测试的代码被推送。
+4. **Commit 信息校验**
+   在 `commit-msg` hook 中使用 [commitlint](https://github.com/conventional-changelog/commitlint) 强制提交信息符合规范（如 Conventional Commits）。
+
+## 3. 如何使用 Husky？
+
+### 安装
+
+```bash
+npm install husky --save-dev
+```
+
+### 初始化
+
+```bash
+npx husky init
+```
+
+这会生成一个 `.husky` 目录，并在里面创建 `pre-commit` 文件，默认内容可能是：
+
+```bash
+#!/bin/sh
+npm test
+```
+
+### 添加 Hook
+
+假设你想在提交前运行 ESLint，可以这样：
+
+```bash
+npx husky add .husky/pre-commit "npm run lint"
+```
+
+生成的 `.husky/pre-commit` 文件类似：
+
+```bash
+#!/bin/sh
+npm run lint
+```
+
+### 使用 commit-msg 校验提交信息
+
+先装 commitlint：
+
+```bash
+npm install @commitlint/{config-conventional,cli} --save-dev
+```
+
+创建配置文件 `commitlint.config.js`：
+
+```js
+module.exports = { extends: ['@commitlint/config-conventional'] }
+```
+
+添加 hook：
+
+```bash
+npx husky add .husky/commit-msg "npx --no-install commitlint --edit $1"
+```
+
+这样，若提交信息不符合规范，会被拦截。
+
+## 4. 和 lint-staged 搭配
+
+通常 Husky 会和 [lint-staged](https://github.com/okonet/lint-staged) 搭配使用：
+只检查本次改动的文件，而不是全量检查。
+
+示例：
+`package.json` 里加：
+
+```json
+{
+  "lint-staged": {
+    "*.js": "eslint --fix",
+    "*.ts": "eslint --fix"
+  }
+}
+```
+
+然后在 `.husky/pre-commit` 文件中写：
+
+```bash
+npx lint-staged
+```
+
+## 总结
+
+- **Husky** 是一个 Git hooks 工具，用来在 commit、push 等阶段运行脚本。
+- 主要用于 **代码质量控制**：lint、格式化、测试、commit message 校验等。
+- 使用方式：安装 → 初始化 → 添加 hooks → 编写脚本。

package/templates/vitepress/tools/lint-staged.md

@@ -0,0 +1,79 @@
+# lint-staged
+
+## 1. 什么是 lint-staged？
+
+**lint-staged** 是一个工具，主要功能是：
+在 **Git 暂存区（staged）里的文件** 上运行你指定的 linters 或脚本。
+
+👉 它和 **Husky** 搭配使用最常见：
+
+- Husky 负责触发 Git hooks（比如 `pre-commit`）。
+- lint-staged 负责只对 **本次提交涉及的文件** 进行检查和修复。
+
+这样就避免了对整个项目运行 lint/format，节省时间。
+
+## 2. lint-staged 有什么用？
+
+- **提高性能**：只检查本次改动的文件，而不是全量跑 `eslint` 或 `prettier`。
+- **保证提交质量**：阻止不符合规范的代码进入仓库。
+- **常见场景**：
+  - 运行 ESLint 自动修复：`eslint --fix`
+  - 运行 Prettier 格式化：`prettier --write`
+  - 运行 TypeScript 编译检查：`tsc --noEmit`
+  - 优化图片、转换 Markdown 等自定义脚本
+
+## 3. 如何使用 lint-staged？
+
+### 安装
+
+```bash
+npm install lint-staged --save-dev
+```
+
+### 配置
+
+lint-staged 支持在 `package.json`、`.lintstagedrc` 或 `lint-staged.config.js` 中配置。
+
+最简单的方式：在 `package.json` 加上：
+
+```json
+{
+  "lint-staged": {
+    "*.js": "eslint --fix",
+    "*.ts": "eslint --fix",
+    "*.{js,ts,json,css,md}": "prettier --write"
+  }
+}
+```
+
+### 结合 Husky
+
+一般在 `.husky/pre-commit` 中加：
+
+```bash
+npx lint-staged
+```
+
+这样在提交时，lint-staged 会自动处理已暂存的文件。
+
+## 4. 示例工作流
+
+假设你改了两个文件：
+
+- `src/app.js`
+- `docs/readme.md`
+
+然后执行 `git add . && git commit -m "feat: add app"`
+
+在 `pre-commit` hook 中，lint-staged 会只对这两个文件运行配置的命令，比如：
+
+- `eslint --fix src/app.js`
+- `prettier --write docs/readme.md`
+
+最终确保这两个文件在提交之前符合规范。
+
+## 总结
+
+- **lint-staged = 只在 staged 文件上运行 lint/脚本的工具**。
+- 优点：快、精准，避免全量检查。
+- 常和 **Husky** 搭配，用于 `pre-commit`。

package/templates/vitepress/tools/pnpm.md

@@ -0,0 +1,101 @@
+# pnpm
+
+## 1. 什么是 pnpm？
+
+**pnpm** 是一种 Node.js 的包管理器（类似于 **npm** 和 **yarn**）。
+名字里的 **p** 代表 **Performant（高性能）**，也有人说是 **“poor man's npm”** 😂。
+
+它的核心特点是：
+
+- 使用 **硬链接 + 符号链接** 的方式来存储依赖。
+- 避免不同项目重复下载相同的依赖，大大节省磁盘空间。
+- 更快的安装速度。
+
+## 2. pnpm 有什么用？
+
+### 🚀 性能和空间优势
+
+- **npm/yarn**：每个项目都要复制一份完整的依赖到 `node_modules`。
+- **pnpm**：把所有依赖放在一个全局的 **内容可寻址存储（content-addressable store）**，项目里只是通过符号链接指向。
+
+结果就是：
+
+- 相同的依赖只会存一份。
+- 安装速度更快，磁盘占用更小。
+
+### 📦 严格的依赖隔离
+
+- 在 `npm` 或 `yarn` 中，`node_modules` 会形成一个“扁平化”结构，有时可能让项目误依赖到不是自己声明的包（幽灵依赖问题）。
+- **pnpm** 使用符号链接保持严格的依赖树，避免隐式依赖。
+  👉 如果你的 `package.json` 里没声明，就无法直接引用。
+
+### 🛠 Monorepo 支持更好
+
+- `pnpm` 原生支持 monorepo 管理（工作空间 `pnpm-workspace.yaml`）。
+- 比如在一个仓库里有多个子包，`pnpm` 可以高效地安装和链接它们，代替 Lerna、Yarn workspaces 等工具。
+
+### 🌍 与 npm 生态完全兼容
+
+- `pnpm` 底层还是调用 npm registry，所以和 npm 包生态 **100%兼容**。
+- 使用方式也和 `npm` 很接近，学习成本低。
+
+## 3. 如何使用 pnpm？
+
+### 安装 pnpm
+
+```bash
+npm install -g pnpm
+```
+
+### 常用命令对照
+
+| 操作       | npm                | pnpm             |
+| ---------- | ------------------ | ---------------- |
+| 安装依赖   | `npm install`      | `pnpm install`   |
+| 安装某个包 | `npm install xx`   | `pnpm add xx`    |
+| 移除某个包 | `npm uninstall xx` | `pnpm remove xx` |
+| 更新依赖   | `npm update`       | `pnpm update`    |
+| 初始化项目 | `npm init`         | `pnpm init`      |
+
+### Monorepo 示例
+
+创建 `pnpm-workspace.yaml`：
+
+```yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - 'templates/*'
+```
+
+这样 `pnpm` 会自动管理多个子项目的依赖和链接。
+
+## 总结
+
+- **pnpm 是一种更快、更省空间、更严格的包管理器**。
+- 核心优势：
+  1. **磁盘节省**（共享依赖存储）。
+  2. **安装速度快**。
+  3. **严格依赖管理**，避免幽灵依赖。
+  4. **原生支持 monorepo**。
+
+## npm vs Yarn vs pnpm 对比表
+
+| 特性 / 工具       | **npm**                          | **Yarn**                      | **pnpm**                               |
+| ----------------- | -------------------------------- | ----------------------------- | -------------------------------------- |
+| **生态兼容性**    | ✅ 官方，100% 兼容 npm registry  | ✅ 兼容 npm registry          | ✅ 兼容 npm registry                   |
+| **安装速度**      | ⏳ 较慢（尤其是全量安装时）      | 🚀 比 npm 快，缓存优化        | ⚡ 非常快（硬链接 + 全局存储机制）     |
+| **磁盘空间占用**  | 📦 高，每个项目一份完整依赖      | 📦 中等，有缓存但依赖重复存储 | 🪶 很低，共享依赖存储，节省大量空间    |
+| **依赖结构**      | 扁平化，可能产生“幽灵依赖”       | 扁平化，依旧可能有幽灵依赖    | 严格隔离，避免幽灵依赖                 |
+| **Monorepo 支持** | 🚫 无原生支持，需要 Lerna 等工具 | ⚠️ Yarn Workspaces 支持       | ✅ 原生支持 Workspaces，管理更高效     |
+| **命令兼容性**    | 标准 npm 命令                    | 大部分与 npm 相似             | 基本兼容，部分命令略有不同（如 `add`） |
+| **锁文件**        | `package-lock.json`              | `yarn.lock`                   | `pnpm-lock.yaml`                       |
+| **稳定性**        | ✅ 官方维护，稳定性高            | ✅ 较成熟，社区维护           | ✅ 越来越流行，性能最佳                |
+| **学习成本**      | ⭐⭐ 最低                        | ⭐⭐ 略有差异（命令相似）     | ⭐⭐⭐ 略高，但上手简单                |
+| **适用场景**      | 小型项目，或默认环境             | 中大型项目，需要更快安装      | 中大型/Monorepo 项目，重视性能和空间   |
+
+## 对比总结
+
+- **npm**：默认选择，生态最广，适合一般小型项目。
+- **Yarn**：性能较优，适合需要加快依赖安装的团队。
+- **pnpm**：性能最好、磁盘最省、依赖最严格，特别适合 **大型项目** 和 **monorepo** 场景。

package/templates/vitepress/tools/renovate.md

@@ -0,0 +1,91 @@
+# Renovate
+
+## 1. 什么是 Renovate？
+
+**Renovate** 是一个开源的 **依赖更新自动化工具**。
+它能帮你在项目中自动检测过期的依赖，并通过 PR（Pull Request）的形式提交更新建议。
+
+👉 简单来说：
+
+- 你不需要手动检查 `package.json`、`requirements.txt` 等文件里的依赖是否过期。
+- Renovate 会帮你自动发现并发起更新。
+
+## 2. Renovate 有什么用？
+
+### 🚀 核心价值
+
+1. **自动化依赖升级**
+   - 自动扫描项目依赖（支持 Node.js、Python、Java、Go、Docker 等）。
+   - 自动检测新版本。
+   - 自动提交 PR。
+
+2. **降低维护成本**
+   - 避免依赖长期不升级，导致一次性大版本升级困难。
+   - 减少安全漏洞（及时更新安全补丁版本）。
+
+3. **可控性强**
+   - 你可以配置哪些依赖自动升级，哪些只做提醒。
+   - 可以选择自动合并 **patch/minor** 版本更新，而 **major** 版本需要人工 review。
+
+4. **支持 Monorepo**
+   - 非常适合 monorepo 项目，能分别更新各个子包的依赖。
+
+## 3. Renovate 怎么用？
+
+### 方式一：作为 GitHub App
+
+1. 打开 [Renovate GitHub App](https://github.com/apps/renovate) 并安装到你的仓库。
+2. 它会自动在项目根目录生成一个配置文件 `renovate.json`（或 `renovate.json5`）。
+3. Renovate 就会定期检查依赖，并创建 PR。
+
+### 方式二：自托管
+
+如果你不想用 GitHub App，可以自己部署 Renovate（适用于 GitLab、Bitbucket 等环境）。
+
+```bash
+npx renovate
+```
+
+### 配置示例
+
+在项目根目录添加 `renovate.json`：
+
+```json
+{
+  "extends": ["config:base"],
+  "packageRules": [
+    {
+      "matchUpdateTypes": ["minor", "patch"],
+      "automerge": true
+    },
+    {
+      "matchUpdateTypes": ["major"],
+      "automerge": false
+    }
+  ]
+}
+```
+
+解释：
+
+- 使用基础配置 `"extends": ["config:base"]`。
+- **minor/patch 更新** 自动合并。
+- **major 更新** 需要人工 review。
+
+### 实际效果
+
+- Renovate 会创建类似这样的 PR：
+  - `chore(deps): update dependency react from 18.2.0 to 18.3.0`
+  - `fix(deps): update dependency lodash from 4.17.20 to 4.17.21`
+
+- 你可以选择直接合并，或者再测试后手动处理。
+
+## 4. 总结
+
+- **Renovate = 自动依赖升级管家**。
+- 主要用途：**自动检测依赖更新、自动生成 PR、降低维护成本**。
+- 使用方式：安装 GitHub App（最简单），或者自托管运行。
+- 适用场景：
+  - 需要长期维护的项目。
+  - 对安全性敏感的项目（及时更新补丁）。
+  - Monorepo 项目，依赖多而复杂。