@icebreakers/monorepo-templates 1.0.15 → 1.2.0

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.

package/templates/vitepress/why/js-cjs-mjs.md

@@ -1,99 +1,12 @@
-# js 文件的各种后缀
+# JavaScript Module Extensions
 
-下面用一张“速查表”+要点说明，把这些扩展名分别讲清楚，并说明各自**在什么情况下会被当作可执行模块加载**，以及**谁来消费它**。
+Node.js uses file extensions and the nearest `package.json` `type` field to determine module format.
 
-## 速查表
+| Extension       | Meaning                                       |
+| --------------- | --------------------------------------------- |
+| `.mjs`          | Always ES module                              |
+| `.cjs`          | Always CommonJS                               |
+| `.js`           | Depends on `package.json` `type`              |
+| `.mts` / `.cts` | TypeScript source with explicit module intent |
 
-| 扩展名  | 语义                                               | 由谁执行/消费                                        | 何时被当作“可运行的模块”加载                                                                                                                                                                                                      |
-| ------- | -------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.js`   | JavaScript 源码（CJS 或 ESM，取决于上下文）        | Node、浏览器、打包器                                 | **Node**：受 `package.json` 的 `"type"` 影响——`"type":"module"` 时按 **ESM** 解析，否则按 **CommonJS**。**浏览器**：始终当作 JS，是否是模块取决于 `<script type="module">`（ESM）还是普通 `<script>`（经典脚本）。                |
-| `.cjs`  | JavaScript（**强制 CommonJS**）                    | Node、打包器                                         | **Node**：始终按 **CommonJS** 加载，与 `package.json` 的 `"type"` 无关。                                                                                                                                                          |
-| `.mjs`  | JavaScript（**强制 ESM**）                         | Node、浏览器、打包器                                 | **Node**：始终按 **ESM** 加载。**浏览器**：当作普通 JS 文件；是否作为模块取决于 `<script type="module">`。                                                                                                                        |
-| `.ts`   | TypeScript 源码（模块语义由编译目标/解析策略决定） | **TS 编译器/工具链**（tsc、ts-node、tsx、Vite 等）   | 不是原生可执行；需经编译或运行时加载器将其转成 `.js`。在 TS 的 `moduleResolution`=NodeNext/Node16 下，`.ts` 的产物会遵循对应的 CJS/ESM 规则。                                                                                     |
-| `.cts`  | TypeScript，**指定生成 CommonJS**                  | TS 编译器/工具链                                     | 同上；不由 Node 直接执行。编译后产出 `.cjs/.js`（CJS 语义），并可生成 `.d.cts`。                                                                                                                                                  |
-| `.mts`  | TypeScript，**指定生成 ESM**                       | TS 编译器/工具链                                     | 同上；不由 Node 直接执行。编译后产出 `.mjs/.js`（ESM 语义），并可生成 `.d.mts`。                                                                                                                                                  |
-| `.d.ts` | **类型声明文件**（仅类型，无运行时）               | TypeScript 编译器、编辑器/语言服务、打包器的类型阶段 | **永不执行**。仅在类型检查/智能提示/发布类型时被“读取”。若包的 `package.json` 有 `"types": "index.d.ts"`（或在 `exports` 的 `types`/ `typesVersions` 配置），TS 会用它做类型来源。也存在 `.d.mts` / `.d.cts` 变体以对应 ESM/CJS。 |
-
-## 关键规则与细节
-
-1. **Node.js 如何决定 CJS vs ESM（针对 `.js`）**
-   - 在某个包目录（有 `package.json`）下：
-     - `package.json` 有 `"type": "module"` → 该目录内的 **`.js`** 默认视作 **ESM**。
-     - 否则（默认 `"type":"commonjs"`）→ **`.js`** 默认视作 **CommonJS**。
-
-   - **`.mjs` 一律 ESM，`.cjs` 一律 CJS**，不受 `"type"` 影响。
-   - 混合项目的常见做法：`"type":"module"` + 把需要 CJS 的文件命名为 `.cjs`；或反之。
-
-2. **浏览器如何加载**
-   - 浏览器不关心 `.mjs/.cjs` 这些“Node 语义”扩展名本身；它看的是 `<script>` 标签：
-     - `<script type="module" src="...">` → ESM 模式（支持 `import`）。
-     - `<script src="...">` → 经典脚本（全局作用域，无模块语义）。
-
-   - 资源的 **MIME 类型** 需正确（如 `text/javascript`）；文件扩展名不是决定性因素。
-
-3. **TypeScript 文件（`.ts/.mts/.cts`）何时“会被加载”？**
-   - **Node 原生不会执行 TS**。你需要：
-     - 先用 **`tsc`** 编译为 `.js/.mjs/.cjs` 再由 Node 加载；或
-     - 使用运行时加载器/执行器（如 **ts-node、tsx、Bun** 或打包器 dev server）在内存里**即时转译**后再交给 JS 运行时执行。
-
-   - **`.mts` / `.cts` 的意义**：在 TS 4.7+ 的 `moduleResolution: "NodeNext"/"Node16"` 下，明确告知“这是要编译成 ESM/CJS 的 TS 文件”。这能避免仅用 `.ts` 时的二义性。
-   - 生成声明文件时会对应地产生 `.d.mts` / `.d.cts`。
-
-4. **`.d.ts`（与 `.d.mts/.d.cts`）何时被“读取”**
-   - **只在类型系统中使用**：编译（`tsc`）、编辑器智能提示、类型检查、`npm publish` 时作为类型入口。
-   - 定位方式：
-     - 包内 `package.json` 的 `"types"` / `"typings"` 字段；
-     - `exports` 的 `types`（或 `typesVersions`）；
-     - `typeRoots`、`types`、三斜线指令 `/// <reference types="...">`；
-     - `@types/*` 包（DefinitelyTyped）。
-
-   - **运行时绝不加载/执行**。
-
-5. **打包器（Vite、Webpack、Rollup、esbuild）**
-   - 都把 **`.mjs` 当 ESM**、**`.cjs` 当 CJS**。
-   - 会通过插件/内置加载 TS（把 `.ts/.mts/.cts` 转成 JS）。
-   - 会遵守 `exports`/`module`/`main`/`type` 等字段来选择入口与格式。
-   - 对于 Node 产物，常见是同时发布 ESM 与 CJS 两套构建（双包架构），并提供相应的 `.d.ts`。
-
-## 示例
-
-**Node + `"type":"module"` 情况：**
-
-```txt
-pkg/
-  package.json  // { "type": "module" }
-  index.js      // 按 ESM 解析
-  legacy.cjs    // 按 CJS 解析
-  util.mjs      // 按 ESM 解析
-```
-
-**TypeScript 在 NodeNext 下的布局：**
-
-```txt
-src/
-  index.mts     // 编译为 ESM（.mjs）；会配套生成 index.d.mts（若开启声明）
-  loader.cts    // 编译为 CJS（.cjs）；会配套生成 loader.d.cts
-  types.d.ts    // 仅类型，运行时不参与
-```
-
-**浏览器：**
-
-```html
-<!-- 经典脚本（非模块） -->
-<script src="/app.js"></script>
-
-<!-- ESM 模块 -->
-<script type="module" src="/main.js"></script>
-```
-
-## 实战建议
-
-- **库作者**：建议产出 **双格式**（CJS+ESM）与**类型声明**，并在 `package.json` 设置：
-  - `"type": "module"`（若以 ESM 为主），再提供 CJS 入口（`.cjs`）；
-  - 使用 `exports` 指定 `import`/`require` 条目与 `types`。
-
-- **应用作者**：统一风格更省心。若全量 ESM，就：
-  - `"type":"module"` + 统一 `.js/.mjs`（或 TS 中用 `.mts`）；
-  - 依赖里若有 CJS 包，让打包器或 Node 的兼容层处理。
-
-- **TS 工程**：用 **`moduleResolution: "NodeNext"`**，并用 `.mts/.cts` 明确产物语义；发布时别忘了 `.d.ts`/`.d.mts/.d.cts`。
+For published libraries, make the package `exports` map explicit and test both import and require paths when both formats are supported.