@icebreakers/monorepo 1.2.0 → 1.2.1

package/templates/apps/website/why/js-keywords.md

@@ -0,0 +1,132 @@
+# CJS 和 ESM 关键字/全局变量对比
+
+## 📦 CommonJS (CJS)
+
+CJS 是 Node.js 默认的老模块系统，使用 `require` 和 `module.exports`。
+
+### 核心关键字 / 全局变量
+
+- **`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。 -->

package/templates/apps/website/why/modern/bundlers.md

@@ -0,0 +1,79 @@
+# 使用打包器
+
+## 选择打包器
+
+一般来说，在不同场景下，需要使用不同的打包器，以下是我的选择:
+
+- `webpack` 我不用，因为打出来的产物代码丑，配置复杂
+- `rollup` 我最早用的就是这个，现在不用因为要装的包太多了，而且需要你对打包器有一定的理解，在打包复杂需要高度自定义的场景下使用
+- `esbuild` 用的少，直接用不是很方便，但是可以基于它做高度自定义(写插件)
+- `tsup` 基于 `esbuild` 的傻瓜无脑式的打包器，非常好用
+- `unbuild` 基于 `rollup` 的傻瓜无脑式的打包器，众多 `vite plugin` 源代码的御用打包器，还有基于 `jiti` 的 `stub` 模式，非常好用
+- `vite` 基于 `rollup` 的打包器，假如你需要构建前端组件，这个就是首选，毕竟你也懒得去自己处理各种各样的样式文件吧，比如打包新版本 `vue` 组件，只能使用这个的库模式进行打包。
+- `rolldown`/`tsdown` 暂时不太稳定，等出正式版本再观望一段时间
+
+所以本篇文章，主要介绍 `tsup` 和 `unbuild` 这两个通用打包器的使用和配置方式，以及 `vite` 库模式进行打包 `vue` 组件，其他的请自行查看对应的文档。
+
+## tsup
+
+本项目的模板之一 [tsup-template](https://github.com/sonofmagic/monorepo-template/tree/main/packages/tsup-template)
+
+:::code-group
+
+```ts [tsup.config.ts]
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  entry: ['src/index.ts'], // , 'src/cli.ts'],
+  shims: true,
+  format: ['cjs', 'esm'],
+  clean: true,
+  dts: true,
+  cjsInterop: true,
+  splitting: true,
+  outExtension({ format }) {
+    return {
+      js: `.${format === 'esm' ? 'mjs' : 'cjs'}`,
+    }
+  },
+})
+```
+
+:::
+
+## unbuild
+
+本项目的模板之一 [unbuild-template](https://github.com/sonofmagic/monorepo-template/tree/main/packages/unbuild-template)
+
+:::code-group
+
+```ts [build.config.ts]
+import path from 'node:path'
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: ['./src/index'],
+  rollup: {
+    inlineDependencies: true,
+    emitCJS: true,
+    cjsBridge: true,
+    dts: {
+      respectExternal: false,
+    },
+  },
+  alias: {
+    '@': path.resolve(__dirname, './src'),
+  },
+  declaration: true,
+})
+```
+
+:::
+
+## vite
+
+本项目的模板之一 [vue-lib-template](https://github.com/sonofmagic/monorepo-template/tree/main/packages/vue-lib-template)
+
+你可以在 [`vite` 库模式官方文档](https://vite.dev/guide/build.html#library-mode) 来查看打包 `vue` 组件的方式
+
+当然这些都已经被配置在 [vue-lib-template](https://github.com/sonofmagic/monorepo-template/tree/main/packages/vue-lib-template) 中了

package/templates/apps/website/why/modern/dts.md

@@ -0,0 +1,95 @@
+# 添加 dts
+
+## `.d.ts` 文件是什么
+
+在 TypeScript 中，`.d.ts` 文件是 **类型声明文件**，全称是 **"declaration file"**。它的主要作用是为 JavaScript 代码或没有类型定义的 TypeScript 代码提供类型信息。
+
+你安装使用刚刚自己发的包的时候，有没有注意到，你的 `IDE` 没有出现任何的智能提示
+
+这是因为你没有为你的包提供任何的 `dts`, 也就是 `xxx.d.ts` 文件
+
+下面这 2 个标志想必大家在 `npmjs` 进行搜索的时候都见到过。
+
+<img width="40" src="../assets/npm-ts.svg" />
+
+这个标志代表这个包发布的时候，本身包里面就自己提供了 `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" />
+
+这个标志代表这个包发布的时候，本身包里面没有 `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" />
+<div class="text-5xl mx-5">></div>
+<img class="w-12" src="../assets/npm-dt.svg" />
+<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`）
+- 安装类型定义包：
+  ```
+  npm install --save-dev @types/express
+  ```

package/templates/apps/website/why/modern/esm-vs-cjs.md

@@ -0,0 +1,84 @@
+# ESM vs CJS
+
+在 Node.js 中，ESM（ECMAScript Modules）和 CJS（CommonJS）是两种模块系统。ESM 是 JavaScript 官方标准的模块系统，而 CJS 是 Node.js 最初采用的模块系统。
+
+## ESM 相对 CJS 的优势
+
+### 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()
+```

package/templates/apps/website/why/modern/index.md

@@ -0,0 +1,55 @@
+---
+outline: [2, 4]
+---
+
+# 改进并发布现代 npm 包
+
+刚刚我们发布了一个低质量的 `npm` 包，因为它
+
+1. 没有类型提示
+2. 使用了落后的 CJS 语法
+3. 没有使用打包器进行构建，导致无法做语法降级，这可能在低版本的浏览器/Nodejs中出现问题
+4. 没有写 README 别人根本不知道怎么用
+5. 没有单元测试，导致出现问题修改时，容易把原先好的case改坏等等。
+
+为此我们需要提升包的质量，具体的手段如下
+
+此代码的演变用例见 [examples](https://github.com/sonofmagic/monorepo-template/tree/main/apps/website/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` 文档

package/templates/apps/website/why/modern/package-entry-points.md

@@ -0,0 +1,128 @@
+---
+outline: [2, 4]
+---
+
+# package.json 中的 entry point 字段
+
+在 `package.json` 中，定义模块的入口点 (`entry point`) 字段是及其重要的
+
+## package.json 代码示例
+
+```jsonc
+{
+  "name": "icebreaker-npm-basic-package",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./index.cjs", // CommonJS 主入口（用于 Node require）
+  "module": "./index.mjs", // 非标准，但很多构建工具支持（ESM）
+  "types": "./index.d.ts", // TypeScript 类型定义
+  "exports": {
+    ".": {
+      "types": "./index.d.ts", // TypeScript 类型定义
+      "require": "./index.cjs", // Node require 使用 CommonJS
+      "import": "./index.mjs" // Node import 使用 ESM
+    }
+  }
+}
+```
+
+### 📝 字段说明：
+
+| 字段               | 说明                                             |
+| ------------------ | ------------------------------------------------ |
+| `"type": "module"` | 默认将 `.js` 文件视为 ESM                        |
+| `"main"`           | Node 中 `require('pkg')` 会使用 CommonJS 文件    |
+| `"module"`         | 给打包工具提供 ESM 入口，非标准，但有用          |
+| `"exports"`        | 更现代且明确的方式，指明模块格式，兼容 Node >=12 |
+| `"types"`          | 给 TypeScript 指明类型定义文件的位置             |
+
+---
+
+官方文档: [package-entry-points](https://nodejs.org/api/packages.html#package-entry-points)
+
+## 为什么说 module 是非标准的?
+
+在 `package.json` 中，`"module"` 字段是一个 **非标准的字段**，但在现代前端工具（如 Webpack、Rollup、Vite 等）中被广泛使用，用于指向 **ES Module 格式的入口文件**，以便这些工具能够做更好的静态分析与 tree-shaking。
+
+下面是不同工具/环境下可能会读取 `"module"` 字段的情况：
+
+---
+
+### ✅ **什么情况下会加载 `"module"` 字段？**
+
+#### **打包工具（Webpack、Rollup、Vite、Snowpack, Parcel 等）**
+
+- 当你使用这些工具打包代码时，它们会优先尝试读取：
+  1. `"exports"` 字段（如果存在，优先于其他字段）
+  2. `"module"` 字段（通常表示 ESM 格式）
+  3. `"main"` 字段（通常表示 CommonJS 格式）
+
+示例：
+
+```js
+// 在 Webpack 中引入某个 npm 包时，如果该包的 package.json 有 module 字段
+// Webpack 会优先使用这个字段所指向的 ESM 文件
+import foo from 'icebreaker-npm-basic-package'
+```
+
+> `Vite、Snowpack, Parcel` 这些工具天生以 ESM 为主，会优先读取 `"module"` 字段。
+
+---
+
+### 🚫 **不会加载 `"module"` 字段的情况**
+
+#### **Node.js 本身**
+
+- Node.js 并不识别 `"module"` 字段，加载模块时它依赖的是：
+  - `"type"` 字段（决定是否为 ESM 模式）
+  - `"main"` 字段（默认入口）
+  - 或者直接通过 `"exports"` 字段（推荐现代做法）
+
+例如，在你的 `package.json` 中：
+
+```json
+{
+  "type": "module",
+  "main": "index.cjs",
+  "module": "index.js"
+}
+```
+
+- 你运行 `node .` 时，Node 会根据 `"main"` 加载 `index.cjs`
+- 如果你运行 `node index.js`，它会根据文件扩展名和 `"type": "module"` 以 ESM 模式运行，但并不会自动从 `"module"` 字段寻找入口
+
+---
+
+### 推荐现代做法（如要兼容多种环境）：
+
+可以使用 `exports` 字段更明确地配置入口文件：
+
+```jsonc
+{
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.cjs",
+      "import": "./index.js"
+    },
+    "./xxx": {
+      "types": "./xxx.d.ts",
+      "require": "./xxx.cjs",
+      "import": "./xxx.js"
+    }
+  }
+}
+```
+
+这样，Node.js 和打包工具都能正确识别和区分 ESM 和 CommonJS。
+
+---
+
+### 总结：
+
+| 环境/工具      | 是否使用 `"module"` 字段 | 说明                          |
+| -------------- | ------------------------ | ----------------------------- |
+| Node.js        | ❌ 不会使用              | 使用 `"main"` 或 `"exports"`  |
+| Webpack/Rollup | ✅ 会使用                | 优先用来加载 ESM 版本         |
+| Vite/Snowpack  | ✅ 会使用                | 用于选择 ESM 格式             |
+| TypeScript     | ❌ 不直接使用            | 会用 `"types"` 字段找类型声明 |