@icebreakers/monorepo-templates 1.1.0 → 1.2.0

package/templates/vitepress/tools/pnpm.md

@@ -1,127 +1,15 @@
 # pnpm
 
-repoctl 默认围绕 pnpm workspace 设计。你不需要先掌握 pnpm 的所有细节，但要理解这三个事实：
-
-- `pnpm-workspace.yaml` 决定哪些目录属于 workspace。
-- `pnpm install` 会把 workspace 包链接起来。
-- 根脚本，例如 `pnpm doctor`、`pnpm new`、`pnpm check`，最终会调用 repoctl 的 `repo` CLI。
-
-## 在 repoctl 项目里怎么用 pnpm
+pnpm owns workspace discovery, dependency installation, script execution, and versioning configuration.
 
 ```bash
 pnpm install
-pnpm add -D repoctl
-pnpm doctor
-pnpm new sdk --template tsdown
-pnpm check
+pnpm --filter <package> build
+pnpm -r test
+pnpm change
+pnpm change status
 ```
 
-| 命令                  | 在 repoctl 工作流里的作用     |
-| --------------------- | ----------------------------- |
-| `pnpm install`        | 安装依赖并创建 workspace link |
-| `pnpm add -D repoctl` | 给已有仓库接入 repoctl CLI    |
-| `pnpm doctor`         | 通过根脚本运行 `repo doctor`  |
-| `pnpm new`            | 通过根脚本运行 `repo new`     |
-| `pnpm check`          | 通过根脚本运行 `repo check`   |
-
-继续看：[repoctl 快速开始](../repoctl/getting-started.md)。
-
-## 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 项目，重视性能和空间   |
-
-## 对比总结
+`pnpm-workspace.yaml` is the source of truth for package patterns and release groups. repoctl can diagnose missing patterns and synchronize recommended defaults, but pnpm remains the package manager.
 
-- **npm**：默认选择，生态最广，适合一般小型项目。
-- **Yarn**：性能较优，适合需要加快依赖安装的团队。
-- **pnpm**：性能最好、磁盘最省、依赖最严格，特别适合 **大型项目** 和 **monorepo** 场景。
+Prefer exact workspace filters in automation and keep `packageManager` plus `engines.node` declared at the repository root.

package/templates/vitepress/tools/renovate.md

@@ -1,91 +1,7 @@
 # Renovate
 
-## 1. 什么是 Renovate？
+Renovate opens dependency update pull requests according to repository policy.
 
-**Renovate** 是一个开源的 **依赖更新自动化工具**。
-它能帮你在项目中自动检测过期的依赖，并通过 PR（Pull Request）的形式提交更新建议。
+Group related tooling updates, respect pnpm workspace constraints, and let the normal build, lint, typecheck, tsd, and test matrix validate each update. Avoid combining unrelated runtime and tooling upgrades when separate review makes regressions easier to isolate.
 
-👉 简单来说：
-
-- 你不需要手动检查 `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 项目，依赖多而复杂。
+repoctl does not replace Renovate. It provides the diagnostic and verification commands that Renovate pull requests can run consistently.

package/templates/vitepress/tools/turborepo.md

@@ -1,166 +1,14 @@
 # Turborepo
 
-在 repoctl 体系里，Turborepo 负责“任务编排和缓存”，repoctl 负责“什么时候该跑哪些任务”。你日常通常不需要直接调用 `turbo`，而是通过根脚本或 `repo check` 间接触发。
+Turborepo runs the monorepo task graph and caches repeatable work.
 
 ```bash
 pnpm build
+pnpm lint
+pnpm typecheck
 pnpm test
-pnpm exec repo check --full
-pnpm exec repo check --json --out reports/check-plan.json
 ```
 
-| 层级                              | 作用                                      |
-| --------------------------------- | ----------------------------------------- |
-| `repo check`                      | 决定校验模式，输出可读或可保存的计划      |
-| 根脚本 `pnpm build` / `pnpm test` | 调用 `turbo run build` / `turbo run test` |
-| `turbo.json`                      | 定义任务依赖、缓存输出和执行策略          |
+Root scripts delegate to `turbo run`. Package scripts define the actual build, lint, typecheck, and test commands; `turbo.json` defines dependencies, inputs, outputs, and cache behavior.
 
-继续看：[repoctl 工作流与 CI](../repoctl/workflows.md)。
-
-## 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 结构，比如：
-
-```txt
-.
-├── 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**：功能最全，适合大型团队，有可视化依赖图、代码生成、跨语言支持，但学习曲线较陡。
+Mark generated artifacts as task outputs and declare upstream dependencies such as `build` before tests that consume built packages.

package/templates/vitepress/why/how-to-reuse-js-code.md

@@ -1,250 +1,9 @@
----
-outline: [2, 4]
----
+# Reusing JavaScript Code
 
-# 如何复用 js 代码
+JavaScript code can be shared through source modules, workspace packages, or published npm packages. The right boundary depends on ownership and consumers.
 
-我们知道，不论在什么编程语言里，复用代码最简单的方案就是 `复制粘贴`
+- Use a local module for code owned by one package.
+- Use a workspace package when multiple projects in the same repository share versioned behavior.
+- Publish an npm package when external repositories need a stable public API.
 
-然而，复制粘贴会导致代码冗余、难以维护，修改一处逻辑时易漏改其它处，增加出错概率，违背“不要重复自己”（DRY）原则。
-
-假如人人写代码都复制粘贴，这会造成一个工程化的地狱，后期维护成本急剧升高。
-
-为此我们需要有效利用 `模块化` 的思路，去提炼，拆分，复用我们写的代码。
-
-## **代码的模块化**
-
-在现代 `JavaScript` 开发中，**模块化**不仅是一种组织代码的结构化方式，更是实现高效代码复用的核心前提。
-
-### 模块化是复用的基础
-
-1. **明确边界，职责单一**
-   模块化将一个大程序拆分为职责清晰、相互独立的功能块（模块）。每个模块完成一个单一任务，这种**高内聚、低耦合**的结构，为复用提供了天然的土壤。
-
-2. **清晰的导入导出机制**
-   通过标准的 `export` 和 `import`（或 `CommonJS` 的 `module.exports` / `require`），开发者可以在不同文件、不同项目中复用相同模块，而无需复制粘贴代码。
-
-3. **便于维护与测试**
-   模块是可单独测试、维护的最小单元。模块化设计使得一个功能变化不会影响其他模块，增强了系统的稳定性和可扩展性。
-
-4. **为构建通用库打下基础**
-   工具函数库（如 `lodash/es-toolkit`）、业务中间件、配置模块、数据处理逻辑等，都是基于模块化原则设计的。只有当代码被封装为模块，它才可能被提取、封装、共享、发布。
-
-### 模块化让复用从被动到主动
-
-非模块化时代的“复用”往往是：
-
-- 复制粘贴代码
-- 修改适配不同上下文
-
-而模块化之后，“复用”变成了：
-
-- 明确接口，按需引入
-- 参数化、配置化、可扩展
-
-这不仅是形式上的进步，更是软件工程层面的范式跃迁。
-
-### js 模块的典型格式
-
-- **ES Modules（现代浏览器/现代 Node.js）**：标准、推荐，使用 `import` / `export`
-- **CommonJS（传统 Node.js）**：使用 `require` / `module.exports`
-- **UMD / IIFE / SystemJS / AMD**：一些老式模块化兼容方案，仍用于一些库的打包格式
-
-#### ES Modules (ESM)
-
-目前大部分新的 `npm` 包都使用这个格式发包，
-
-它最大的特点是，使用 `export` / `import` 将功能函数、类、常量等分别放入独立 `.js` 文件中，动态引入的使用 `import()` 进行引入
-
-```js
-// utils/math.js
-export function add(a, b) {
-  return a + b
-}
-
-export function multiply(a, b) {
-  return a * b
-}
-```
-
-```js
-// main.js
-import { add, multiply } from './utils/math'
-
-console.log(add(2, 3)) // 5
-console.log(multiply(2, 3)) // 6
-```
-
-**这是目前的主流，也是未来的方向**
-
-注意事项：
-
-- 在浏览器中引入，需要使用 `<script type="module">`
-- 在 `Node.js` 中需要 `package.json` 设置 `"type": "module"`
-
----
-
-#### CommonJS (CJS)
-
-在 `ESM` 规范没有被确立之前的社区模块化方案，低版本 `Node.js` 环境使用，高版本 `Node.js` 同时兼容 `CJS` 和 `ESM` 2 种模块化方案和加载策略
-
-最大的特点为，使用 `require` / `module.exports`(`commonjs2`) / `exports`(`commonjs`) 进行模块化
-
-```js
-// utils/math.js
-function add(a, b) {
-  return a + b
-}
-module.exports = { add }
-```
-
-```js
-// app.js
-const { add } = require('./utils/math.js')
-
-console.log(add(5, 10))
-```
-
-新的包不会使用这个格式，目前这个格式的 `npm` 包，也正在逐步向 `ESM` 格式进行迁移
-
-#### AMD (Asynchronous Module Definition)
-
-AMD 是 RequireJS 推广的模块格式，支持异步加载模块，适用于浏览器。
-
-```js
-define('myLib', [], () => {
-  function hello() {
-    return 'Hello from AMD'
-  }
-
-  return {
-    hello
-  }
-})
-```
-
-**已经过时，不要使用!**
-
-#### UMD （Universal Module Definition）
-
-UMD 是为了同时兼容 CommonJS、AMD 和浏览器环境而设计的模块格式。
-
-```js
-(function (root, factory) {
-  if (typeof define === 'function' && define.amd) {
-    // AMD
-    define([], factory)
-  }
-  else if (typeof module === 'object' && module.exports) {
-    // CommonJS
-    module.exports = factory()
-  }
-  else {
-    // Browser global
-    root.myLib = factory()
-  }
-}(this, () => {
-  // 模块内容
-  function hello() {
-    return 'Hello from UMD'
-  }
-
-  return {
-    hello
-  }
-}))
-```
-
-通常在你使用 `vite` 的 `lib` 模式的时候，除了会打一个 `ESM` 包之外，也会打一个 `UMD` 的包，用于 `CDN` + `SSR` 场景下使用。
-
-#### IIFE （Immediately Invoked Function Expression）
-
-IIFE 是立即执行函数表达式，常用于浏览器中，通常暴露到 `window` 上（无模块系统时的“模拟模块”方式）。
-
-https://developer.mozilla.org/en-US/docs/Glossary/IIFE
-
-```js
-(function () {
-  function hello() {
-    console.log('Hello from IIFE')
-  }
-
-  // 暴露到全局
-  window.myLib = {
-    hello
-  }
-})()
-```
-
-#### SystemJS / System.register
-
-`System` 是由 `ES6 Module Loader` 提出的一种格式，现代打包工具（如 `Rollup`）可以输出此格式，用于运行时动态加载 `ES Modules`。
-
-`SystemJS` 就是帮助你在不支持原生 `ESM` 格式的浏览器上(比如IE11)，使用 `ESM` 格式
-
-```js
-System.register(['./constants'], (exports) => {
-  return {
-    execute() {
-      function hello() {
-        console.log('Hello from System')
-      }
-
-      exports('hello', hello)
-    }
-  }
-})
-```
-
-加载方式（需要 `SystemJS` 库）：
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/systemjs/dist/system.js"></script>
-<script>
-  System.import('/path/to/your-module.js').then(({ hello }) => hello())
-</script>
-```
-
-比如 `@vitejs/plugin-legacy` 这个浏览器降级兼容方案，就是使用 `SystemJS` 在老旧的浏览器里面，加载 `ESM` 格式，从而进行兼容的。
-
-#### 参考链接
-
-- [rollupjs](https://rollupjs.org/configuration-options/#output-format)
-- [webpackjs](https://webpack.js.org/configuration/output/#module-definition-systems-1)
-- [esbuild](https://esbuild.github.io/api/#format)
-- [swc](https://swc.rs/docs/configuration/modules)
-- [babel](https://babeljs.io/docs/babel-preset-env#modules)
-- [typescript](https://www.typescriptlang.org/tsconfig/#module)
-
-## 一些复用方式
-
-### **利用路径 alias 复用代码**
-
-在纯 JS 工程中，如果使用构建工具如 Vite / Webpack，可以配置别名路径：
-
-```js
-// vite.config.js
-export default {
-  resolve: {
-    alias: {
-      '@utils': path.resolve(__dirname, 'src/utils')
-    }
-  }
-}
-```
-
-然后在代码中：
-
-```js
-import { add } from '@utils/math.js'
-```
-
-但是这种方式，仅在构建工具中生效，假如一个项目不用任何的构建工具，这个方案就不行了。
-
-### **发布为 npm 本地包 / 私有包 / 公共包**
-
-绝大部的场景都应该使用这个方案，来达到跨项目复用代码的目的。
-
-这也是官方和社区推荐的方案。
-
-接下来让我们开始 `npm` 包发布的旅程吧！
+In a pnpm workspace, declare internal dependencies with the `workspace:` protocol and let the package build produce explicit runtime and type entrypoints.

package/templates/vitepress/why/index.md

@@ -1 +1,14 @@
-# 从 0 到 1 构建 monorepo
+# Building A Modern npm Package
+
+A modern package needs a deliberate module format, export map, declaration strategy, build pipeline, and compatibility policy.
+
+## Guide
+
+- [Modern Package Overview](./modern/index.md)
+- [ESM vs CommonJS](./modern/esm-vs-cjs.md)
+- [Type Declarations](./modern/dts.md)
+- [Package Entry Points](./modern/package-entry-points.md)
+- [Bundlers](./modern/bundlers.md)
+- [TypeScript](./modern/typescript.md)
+
+Runnable evolution examples remain under `why/examples/` and are intentionally excluded from the generated AI documentation index.