@icebreakers/monorepo-templates 1.1.0 → 1.2.0

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.

package/templates/vitepress/why/js-keywords.md

@@ -1,132 +1,7 @@
-# CJS 和 ESM 关键字/全局变量对比
+# ESM and CommonJS Runtime Globals
 
-## 📦 CommonJS (CJS)
+CommonJS provides `require`, `module`, `exports`, `__filename`, and `__dirname`. ES modules use `import`, `export`, `import.meta.url`, and `createRequire` when interoperability is required.
 
-CJS 是 Node.js 默认的老模块系统，使用 `require` 和 `module.exports`。
+Avoid assuming CommonJS globals exist inside ESM. Resolve file paths with `fileURLToPath(import.meta.url)` and prefer static imports so bundlers and type checkers can understand dependencies.
 
-### 核心关键字 / 全局变量
-
-- **`require`**
-  用于导入模块，例如：`const fs = require("fs")`
-- **`module.exports`**
-  导出一个模块的接口对象。
-- **`exports`**
-  是 `module.exports` 的引用，常用于简写导出。
-- **`__filename`**
-  当前模块的绝对路径（包含文件名）。
-- **`__dirname`**
-  当前模块所在目录的绝对路径。
-- **`arguments`**
-  在函数中依然可用，但不是模块特有的（ESM 中的顶层不再支持）。
-
-### 特点
-
-- 模块加载是 **同步的**（`require` 立即执行）。
-- 每个文件就是一个模块，作用域隔离。
-- Node.js 原生支持。
-
-## 🌐 ECMAScript Modules (ESM)
-
-ESM 是 JavaScript 官方标准，现代浏览器和 Node.js 都支持（需要 `.mjs` 或 `package.json` 配置 `"type": "module"`）。
-
-### 核心关键字 / 特性
-
-- **`import`**
-  用于引入模块：
-  - `import fs from "fs"`
-  - `import { readFile } from "fs"`
-
-- **`export`**
-  导出模块：
-  - `export default function() {}`
-  - `export const x = 1`
-
-- **`import.meta`**
-  提供关于当前模块的元信息（例如：`import.meta.url` 获取模块的文件路径 URL）。
-- **`top-level await`**
-  在 ESM 顶层作用域中可以直接使用 `await`。
-
-### 特点
-
-- 模块加载是 **异步的**。
-- 静态结构，编译时可确定依赖关系。
-- 更加标准化，支持 Tree-shaking（构建时优化）。
-
-## 🚧 差异对照表
-
-| 特性             | CommonJS (CJS)               | ECMAScript Modules (ESM)          |
-| ---------------- | ---------------------------- | --------------------------------- |
-| 导入             | `require()`                  | `import`                          |
-| 导出             | `module.exports` / `exports` | `export` / `export default`       |
-| 文件扩展名       | `.cjs` / `.js`               | `.mjs` / `.js`                    |
-| 文件路径变量     | `__filename`, `__dirname`    | ❌（可用 `import.meta.url` 替代） |
-| 模块元信息       | ❌                           | `import.meta`                     |
-| 异步顶层 `await` | ❌                           | ✅                                |
-| 加载方式         | 同步                         | 异步                              |
-
----
-
-👉 例如，ESM 中没有 `__filename` 和 `__dirname`，你需要用以下方式替代：
-
-```js
-import { dirname } from 'node:path'
-// ESM 中获取 __dirname 效果
-import { fileURLToPath } from 'node:url'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-```
-
-## 📦 CommonJS (CJS) — 清除模块缓存
-
-CJS 使用 `require()` 加载模块时，**会把模块对象缓存在 `require.cache` 里**。如果想清除缓存，可以操作这个对象。
-
-### 关键方式
-
-```js
-// 加载模块
-const mod = require('./foo.js')
-
-// 清除缓存
-delete require.cache[require.resolve('./foo.js')]
-
-// 重新加载
-const freshMod = require('./foo.js')
-```
-
-- `require.resolve()` 会返回模块的绝对路径，用它作为 key 来删除缓存。
-- 删除后，再次 `require()` 会重新执行模块代码。
-
-⚠️ 注意：
-
-- 如果模块被多个文件引用，删除缓存只影响 **当前模块**，依赖树中的引用关系可能导致“旧对象”仍在内存中。
-- 所以要真正“重载”模块，有时需要递归删除依赖树的缓存。
-
-## 🌐 ECMAScript Modules (ESM) — 清除模块缓存
-
-ESM 的模块缓存存放在 **`import` 的内部 Module Map** 中，规范里没有暴露直接操作缓存的方法。
-不过在 **Node.js 环境** 中，可以通过 **动态导入 (`import()`)** + **带查询参数** 或 **利用 `vm` / Loader Hooks** 来实现类似效果。
-
-### 常用方式 1：加查询参数绕缓存
-
-```js
-const mod1 = await import(`./foo.js?update=${Date.now()}`)
-const mod2 = await import(`./foo.js?update=${Date.now()}`)
-```
-
-- 每次加上不同的 querystring，就会绕过缓存，强制重新加载。
-
-### 常用方式 2：使用 `import()` + `Module.createRequire`
-
-在 Node.js 18+ 里，可以通过 `vm` 的上下文重新加载模块，不过相对复杂。一般开发调试时用 **动态 `import()` 加 query** 就够了。
-
-## 🚧 对比总结
-
-| 功能               | CommonJS (CJS)                            | ECMAScript Modules (ESM)            |
-| ------------------ | ----------------------------------------- | ----------------------------------- |
-| 缓存位置           | `require.cache`                           | 内部 **Module Map**（不可直接访问） |
-| 清除缓存方法       | `delete require.cache[require.resolve()]` | ❌ 无官方 API                       |
-| 实际可行的清除方法 | 直接删除缓存并重新 `require()`            | 动态 `import()` 加唯一参数绕过缓存  |
-| 典型应用场景       | 热重载、插件系统                          | 热重载、调试时强制刷新模块          |
-
-<!-- 👉 要不要我帮你写一个 **CJS + ESM 通用的“热重载工具函数”**，比如 `reloadModule(path)`，可以自动检测当前运行环境，然后清除缓存并重新加载？这样你写代码时可以直接用，而不用区分 require/import。 -->
+See [ESM vs CommonJS](./modern/esm-vs-cjs.md) for package-level guidance.

package/templates/vitepress/why/modern/bundlers.md

@@ -1,52 +1,5 @@
-# 使用打包器
+# Bundlers
 
-## 选择打包器
+Library bundlers turn source modules into publishable runtime and declaration artifacts. The repository's TypeScript library asset uses [tsdown](https://github.com/sonofmagic/repoctl/tree/main/templates/tsdown), while the Vue library asset adds Vue-specific build and type checking.
 
-一般来说，在不同场景下，需要使用不同的打包器，以下是我的选择:
-
-- `webpack` 我不用，因为打出来的产物代码丑，配置复杂
-- `rollup` 我最早用的就是这个，现在不用因为要装的包太多了，而且需要你对打包器有一定的理解，在打包复杂需要高度自定义的场景下使用
-- `esbuild` 用的少，直接用不是很方便，但是可以基于它做高度自定义(写插件)
-- `vite` 在 Vite 8 中默认基于 `rolldown` + `oxc`，假如你需要构建前端组件，这个就是首选，毕竟你也懒得去自己处理各种各样的样式文件吧，比如打包新版本 `vue` 组件，只能使用这个的库模式进行打包。
-- `rolldown`/`tsdown` 适合更偏向库构建和工具链场景，但生态兼容面和迁移经验仍然不如 `vite`/`rollup` 成熟，是否采用要看你的实际约束
-
-当前这个仓库已经把通用类库模板收敛到 `tsdown`，组件库则继续使用 `vite` 库模式。
-
-## 过时的方案
-
-:::warning 不推荐继续使用
-`tsup` 和 `unbuild` 在这个模板仓库里已经被标记为过时方案，不再作为新项目的推荐构建工具。
-:::
-
-- `tsup` 曾经用于部分 TypeScript 包和服务模板，但现在这些模板已经迁移到 `tsdown`。如果旧项目里还有 `tsup.config.ts`，建议改成 `tsdown.config.ts`，并把 `build` / `dev` 脚本切到 `tsdown`。
-- `unbuild` 曾经用于库包开发时的 stub 流程，但这里的新模板已经统一使用 `tsdown --watch` 处理开发构建。新项目不要继续引入 `unbuild`。
-
-新建 TypeScript 类库优先使用 `tsdown` 模板；Vue 组件库继续使用 `vite` 库模式。
-
-## tsdown
-
-本项目当前的通用类库模板是 [tsdown](https://github.com/sonofmagic/monorepo-template/tree/main/templates/tsdown)
-
-:::code-group
-
-```ts [tsdown.config.ts]
-import { defineConfig } from 'tsdown'
-
-export default defineConfig({
-  entry: ['./src/index.ts'],
-  format: ['cjs', 'esm'],
-  dts: true,
-  clean: true,
-  target: 'node18',
-})
-```
-
-:::
-
-## vite
-
-本项目的模板之一 [vue-lib](https://github.com/sonofmagic/monorepo-template/tree/main/templates/vue-lib)
-
-你可以在 [`vite` 库模式官方文档](https://vite.dev/guide/build.html#library-mode) 来查看打包 `vue` 组件的方式
-
-当然这些都已经被配置在 [vue-lib](https://github.com/sonofmagic/monorepo-template/tree/main/templates/vue-lib) 中了
+Configure entrypoints, external dependencies, output formats, source maps, and declarations according to the package contract. Applications and libraries have different goals: application builds optimize deployment; library builds preserve reusable public boundaries.

package/templates/vitepress/why/modern/dts.md

@@ -1,93 +1,7 @@
-# 添加 dts
+# Type Declarations
 
-## `.d.ts` 文件是什么
+Type declarations are part of a TypeScript package's public API.
 
-在 TypeScript 中，`.d.ts` 文件是 **类型声明文件**，全称是 **"declaration file"**。它的主要作用是为 JavaScript 代码或没有类型定义的 TypeScript 代码提供类型信息。
+Generate `.d.ts` files from the same source revision as runtime output, point `types` and export conditions at files included in the tarball, and use `tsd` tests for important inference and error behavior.
 
-你安装使用刚刚自己发的包的时候，有没有注意到，你的 `IDE` 没有出现任何的智能提示
-
-这是因为你没有为你的包提供任何的 `dts`, 也就是 `xxx.d.ts` 文件
-
-下面这 2 个标志想必大家在 `npmjs` 进行搜索的时候都见到过。
-
-<img width="40" src="../assets/npm-ts.svg" alt="TypeScript built-in types badge" />
-
-这个标志代表这个包发布的时候，本身包里面就自己提供了 `dts`，这个需要在打包生成出 `dts` 之后，在 `package.json` 中，通过 `types` 字段指定了 `dts` 的位置
-
-比如我发的所有包 [weapp-tailwindcss](https://www.npmjs.com/package/weapp-tailwindcss), [weapp-vite](https://www.npmjs.com/package/weapp-vite), [modern-ahocorasick](https://www.npmjs.com/package/modern-ahocorasick) 等等...
-
-<img width="40" src="../assets/npm-dt.svg" alt="DefinitelyTyped badge" />
-
-这个标志代表这个包发布的时候，本身包里面没有 `dts`，但是有好心人给他写了 `dts`，并发布到了 `@types/*` 这个作用域下了，所以这个包等同于也有 `dts`，而且 `vscode` 也在发现你安装了这样的包之后，也会去下载 `@types/*` 这样的包，当然更好的方式是你要显式安装 `@types` 包
-
-举个例子，比如 [lodash](https://www.npmjs.com/package/lodash) 和 [@types/lodash](https://www.npmjs.com/package/@types/lodash)，点击 [lodash](https://www.npmjs.com/package/lodash) `npm` 主页面的这个标志，就直接跳转到 [@types/lodash](https://www.npmjs.com/package/@types/lodash)
-
-> [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped) 这个是微软的仓库，用于发布管理所有的 `@types` 包
-
-这里就需要提到包的质量判断标准，一般来说呈现下面的趋势:
-
-<div class="flex justify-center">
-<div class="flex items-center border p-6">
-
-<img class="w-12" src="../assets/npm-ts.svg" alt="TypeScript built-in types badge" />
-<div class="text-5xl mx-5">></div>
-<img class="w-12" src="../assets/npm-dt.svg" alt="DefinitelyTyped badge" />
-<div class="text-5xl mx-5">></div>
-<div>什么标志都没有的包</div>
-</div>
-</div>
-
----
-
-### `.d.ts` 文件的作用
-
-- **描述模块或库的类型结构**，使 TypeScript 可以进行类型检查和代码补全。
-- **为 JavaScript 库提供类型支持**，例如 jQuery、Lodash、React 等第三方库。
-- **声明全局变量、模块、类、接口、函数等**，而不提供实际实现。
-
----
-
-### 举个简单例子
-
-假设你有一个 JavaScript 文件 `math.js`：
-
-```js
-// math.js
-function add(a, b) {
-  return a + b
-}
-```
-
-你可以写一个 `.d.ts` 文件来告诉 TypeScript 这个模块的类型：
-
-```ts
-// math.d.ts
-declare function add(a: number, b: number): number
-```
-
-这样你在 TypeScript 中使用 `add` 函数时就能获得类型检查和智能提示了。
-
----
-
-### 使用场景
-
-1. **第三方库没有内置类型定义时**
-   - 可以使用 DefinitelyTyped 的类型库（安装例如 `@types/lodash`）；
-   - 或者自己写 `.d.ts` 文件。
-
-2. **为已有的 JS 代码添加类型支持**
-   - 特别是在从 JS 项目逐步迁移到 TS 时。
-
-3. **定义公共 API 接口或模块类型**
-   - 比如声明一个共享的接口模块 `types.d.ts`，全项目通用。
-
----
-
-### 类型声明的获取方式
-
-- 手动编写 `.d.ts`
-- 自动生成（例如通过 `tsc --declaration`）
-- 安装类型定义包：
-  ```bash
-  npm install --save-dev @types/express
-  ```
+Declaration bundling can simplify public output, but it must preserve module augmentation, generics, and referenced types. Always inspect the packed artifact rather than testing source imports alone.

package/templates/vitepress/why/modern/esm-vs-cjs.md

@@ -1,84 +1,7 @@
-# ESM vs CJS
+# ESM vs CommonJS
 
-在 Node.js 中，ESM（ECMAScript Modules）和 CJS（CommonJS）是两种模块系统。ESM 是 JavaScript 官方标准的模块系统，而 CJS 是 Node.js 最初采用的模块系统。
+ES modules are the preferred format for new packages. CommonJS remains relevant when consumers or toolchains still require `require()`.
 
-## ESM 相对 CJS 的优势
+Choose ESM-only when your supported runtime matrix allows it. Publish dual formats only when the compatibility benefit justifies duplicate builds and interop testing.
 
-### 1. **官方标准化**
-
-- **ESM 是 ECMAScript 的官方模块规范**，跨平台和跨环境（如浏览器、Deno）都支持。
-- 更有利于代码的可移植性和与未来标准兼容。
-
-### 2. **静态分析能力更强**
-
-- ESM 使用 `import` / `export`，**在解析阶段即可确定依赖关系**，这让：
-  - Tree Shaking（去除无用代码）成为可能。
-  - 更好地进行工具分析（如 Webpack、Rollup）。
-
-### 3. **支持异步加载**
-
-- ESM 模块加载是**异步的**，允许更灵活的模块加载策略（尤其适合在浏览器环境或网络环境下）。
-- 支持 `import()` 动态导入，可以实现按需加载。
-
-### 4. **更好的模块作用域**
-
-- 每个 ESM 模块都有自己的作用域，**默认是严格模式**（`use strict`），无需显式声明。
-- 避免了 CJS 中的某些副作用或全局变量污染问题。
-
-### 5. **顶层 `await` 支持**
-
-- 在支持的环境下，ESM 模块可以使用**顶层 await**，这在处理异步初始化逻辑时非常方便。
-
-### 6. **统一生态趋势**
-
-- 越来越多的现代 JavaScript 项目和库采用 ESM，比如 Vite、ESBuild、Deno 等工具链优先支持 ESM。
-
----
-
-## 对比小结
-
-| 特性              | ESM                   | CommonJS (CJS)               |
-| ----------------- | --------------------- | ---------------------------- |
-| 模块语法          | `import` / `export`   | `require` / `module.exports` |
-| 加载方式          | 静态分析 + 异步加载   | 运行时同步加载               |
-| 标准化            | 是（ECMAScript 标准） | 否（Node.js 专有）           |
-| Tree Shaking 支持 | ✅                    | ❌                           |
-| 顶层 await 支持   | ✅（Node.js ≥ 14.8）  | ❌                           |
-| 浏览器支持        | ✅                    | ❌                           |
-| 动态导入          | `import()`            | `require()`                  |
-
----
-
-## 使用 ESM 的注意事项（在 Node.js 中）
-
-- `package.json` 中需要设置 `"type": "module"`。
-- 文件扩展名必须为 `.mjs` 或 `.js`（视 `type` 而定）。
-- `__filename`、`__dirname` 等 Node.js CJS 特有变量不可直接使用（需 `import.meta.url` 代替, 高版本 `Nodejs` 可以使用 `import.meta.dirname` 和 `import.meta.filename`）。
-
----
-
-## 适合使用 ESM 的场景
-
-- 对于新项目，不论是前端还是服务端，你应该始终使用 `ESM`。
-- 需要兼容浏览器或打包工具的项目
-- 有 `Tree Shaking` 需求的库开发
-
-## esm 中使用 require
-
-在 `esm` 格式中的 `js` 中使用 `require` 会报错
-
-```sh
-ReferenceError: require is not defined in ES module scope, you can use import instead
-```
-
-另外也有一种适用于 `nodejs` 的 `esm` 中使用 `require` 做法:
-
-```js
-import { createRequire } from 'node:module'
-
-const require = createRequire(import.meta.filename)
-
-const { sayHello } = require('icebreaker-npm-basic-package')
-
-sayHello()
-```
+For dual packages, map `import`, `require`, and `types` conditions explicitly and test each consumer path. Avoid exporting different logical module instances from the two formats.

package/templates/vitepress/why/modern/index.md

@@ -1,55 +1,14 @@
----
-outline: [2, 4]
----
+# Modern Package Guide
 
-# 改进并发布现代 npm 包
+Modern packages should expose a small, explicit API and generate artifacts that match their declared contract.
 
-刚刚我们发布了一个低质量的 `npm` 包，因为它
+## Checklist
 
-1. 没有类型提示
-2. 使用了落后的 CJS 语法
-3. 没有使用打包器进行构建，导致无法做语法降级，这可能在低版本的浏览器/Nodejs中出现问题
-4. 没有写 README 别人根本不知道怎么用
-5. 没有单元测试，导致出现问题修改时，容易把原先好的case改坏等等。
+- Choose ESM-only or intentional dual-package support.
+- Declare every public subpath in `exports`.
+- Emit and test type declarations.
+- Keep development-only files out of the package tarball.
+- Validate the supported Node and bundler matrix.
+- Record public changes through repository versioning.
 
-为此我们需要提升包的质量，具体的手段如下
-
-此代码的演变用例见 [examples](https://github.com/sonofmagic/monorepo-template/tree/main/templates/vitepress/why/examples)
-
-## 确定包的模块入口点
-
-详见 [package-entry-points](./package-entry-points)
-
-## 添加 DTS
-
-类型提示其实就是最好的文档，为了让使用者，能在IDE里面直接点出来方法，类型和枚举，我们需要添加它
-
-详见 [DTS](./dts.md)
-
-## 更改为 ESM 格式优先
-
-优先 ESM 格式符合我们面向未来编程的原则。
-
-详见 [ESM vs CJS](./esm-vs-cjs.md)
-
-## 使用 TypeScript 进行编写
-
-既然我们都要使用一份代码，去生成 `cjs` / `esm` / `dts`，那么我们当然可以完全使用 `TypeScript` 进行编写，去生成对应的产物即可
-
-详见 [使用 TypeScript 编写代码](./typescript)
-
-## 使用打包器
-
-`TypeScript` 自带的 `tsc` 功能太弱了，当我们要进行一些前端工程化的改造时候，光使用 `tsc` + `script脚本` 的方式已经满足不了我们的需求
-
-所有我们这时候需要引入打包器，来和 `TypeScript` 一起协作
-
-详见 [使用打包器](./bundlers)
-
-## 写一份可读的 README
-
-假如你写的 `npm` 包已经复杂到一个 `README.md` 文档无法解决开发者的遇到的问题了，那么就准备一个文档网站
-
-## 添加单元测试(额外)
-
-本模板使用的就是 `vitest`，具体使用方式见 `vitest` 文档
+Start with [ESM vs CommonJS](./esm-vs-cjs.md), then review [entry points](./package-entry-points.md) and [declarations](./dts.md).