refactor

fi3ework · fi3ework · commit 18c447d41e02 · 2025-08-21T14:24:58.000+08:00
diff --git a/website/docs/en/guide/features/esm.mdx b/website/docs/en/guide/features/esm.mdx
@@ -2,31 +2,7 @@ import { Stability } from '@components/ApiMeta';
 
 # ESM output
 
-Rspack supports bundling with ESM format output. By default, Rspack generates bundled output that includes Rspack runtime code rather than standard CommonJS or ESM format. You can configure [output.module](/config/output#outputmodule) to generate standard ESM format output.
-
-Below are the main configuration options related to ESM and their descriptions, which are used when building both applications and libraries.
-
-1. [output.module](/config/output#outputmodule): Set to `true` to generate ESM format output. When this option is enabled, it affects the following configurations:
-   1. Affects [externalsType](/config/externals#externalstype) default value: When `output.module` is `true`, `externalsType` defaults to `'module-import'`
-   2. Affects [output.filename](/config/output#outputfilename) default value: When `output.module` is `true`, the default filename is `'[name].mjs'` instead of `'[name].js'`
-   3. Affects [output.chunkFilename](/config/output#outputchunkfilename) default value: When `output.module` is `true`, chunk filename defaults to `'[id].mjs'` instead of `'[id].js'`
-   4. Affects [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename) default value: When `output.module` is `true`, defaults to `'[id].[fullhash].hot-update.mjs'`
-   5. Affects [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename) default value: When `output.module` is `true`, defaults to `'[runtime].[fullhash].hot-update.json.mjs'`
-   6. Affects [output.iife](/config/output#outputiife) default value: When `output.module` is `true`, `output.iife` defaults to `false`
-   7. Affects [output.library.type](/config/output#outputlibrarytype) default value: When `output.module` is `true`, defaults to `'module'` instead of `'var'`
-   8. Affects [output.scriptType](/config/output#outputscripttype) default value: When `output.module` is `true`, defaults to `'module'`
-   9. Affects [output.environment.dynamicImport](/config/output#outputenvironmentdynamicimport) default value: Enabled when `output.module` is `true`
-   10. Affects [output.environment.dynamicImportInWorker](/config/output#outputenvironmentdynamicimportinworker) default value: Enabled when `output.module` is `true`
-   11. Affects [output.environment.module](/config/output#outputenvironmentmodule) default value: Enabled when `output.module` is `true`
-   12. Affects Node.js related configuration defaults: In Node.js environment, when `output.module` is `true`, `__filename` and `__dirname` default to `'node-module'`
-2. [output.chunkFormat](/config/output#outputchunkformat): Set to `'module'` to use ESM format.
-3. [output.library.type](/config/output#outputlibrarytype): Set to `'modern-module'` for additional optimization of library ESM output format.
-4. [output.chunkLoading](/config/output#outputchunkloading): Set to `'import'` to use ESM `import` for loading chunks.
-5. [output.workerChunkLoading](/config/output#outputworkerchunkloading): Set to `'import'` to use ESM `import` for loading workers.
-6. [optimization.concatenateModules](/config/optimization#optimizationconcatenatemodules): modern-module depends on this option being enabled to ensure the output supports good tree-shaking and correct library exports.
-7. [optimization.avoidEntryIife](/config/optimization#optimizationavoidentryiife): In some cases, Rspack wraps ESM output in an IIFE, which breaks ESM's modular characteristics.
-8. [experiments.outputModule](/config/experiments#experimentsoutputmodule): Enable the experimental feature required for output.module.
-9. [HtmlWebpackPlugin.scriptLoading](/guide/tech/html#htmlwebpackplugin): Set to `'module'` to use ESM `<script type="module">` for loading `.mjs` modules.
+Rspack supports bundling with ESM format output. By default, Rspack generates bundled output that includes Rspack runtime code rather than standard CommonJS or ESM format. You can configure [output.module](/config/output#outputmodule) to generate standard ESM format output. The following sections introduce how to [build application ESM output](#building-application-esm-output) and [build library ESM output](#building-library-esm-output), and finally list the [configuration checklist](#configuration-checklist) related to ESM output.
 
 ## Building application ESM output
 
@@ -93,3 +69,29 @@ Currently, Rspack's ESM support is still being improved. In certain use cases, y
 4. Re-exports of external modules (`export * from '...'`) cannot be properly preserved in ESM format
 
 We are continuously improving Rspack's ESM support to provide a comprehensive solution that addresses existing issues and makes ESM usage more simple and intuitive, better embracing the modern JavaScript module system.
+
+## Configuration Checklist
+
+Below are the main configuration options related to ESM and their descriptions, which are used when building both applications and libraries.
+
+1. [output.module](/config/output#outputmodule): Set to `true` to generate ESM format output. When this option is enabled, it affects the following configurations:
+   1. Affects [externalsType](/config/externals#externalstype) default value: When `output.module` is `true`, `externalsType` defaults to `'module-import'`
+   2. Affects [output.filename](/config/output#outputfilename) default value: When `output.module` is `true`, the default filename is `'[name].mjs'` instead of `'[name].js'`
+   3. Affects [output.chunkFilename](/config/output#outputchunkfilename) default value: When `output.module` is `true`, chunk filename defaults to `'[id].mjs'` instead of `'[id].js'`
+   4. Affects [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename) default value: When `output.module` is `true`, defaults to `'[id].[fullhash].hot-update.mjs'`
+   5. Affects [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename) default value: When `output.module` is `true`, defaults to `'[runtime].[fullhash].hot-update.json.mjs'`
+   6. Affects [output.iife](/config/output#outputiife) default value: When `output.module` is `true`, `output.iife` defaults to `false`
+   7. Affects [output.library.type](/config/output#outputlibrarytype) default value: When `output.module` is `true`, defaults to `'module'` instead of `'var'`
+   8. Affects [output.scriptType](/config/output#outputscripttype) default value: When `output.module` is `true`, defaults to `'module'`
+   9. Affects [output.environment.dynamicImport](/config/output#outputenvironmentdynamicimport) default value: Enabled when `output.module` is `true`
+   10. Affects [output.environment.dynamicImportInWorker](/config/output#outputenvironmentdynamicimportinworker) default value: Enabled when `output.module` is `true`
+   11. Affects [output.environment.module](/config/output#outputenvironmentmodule) default value: Enabled when `output.module` is `true`
+   12. Affects Node.js related configuration defaults: In Node.js environment, when `output.module` is `true`, `__filename` and `__dirname` default to `'node-module'`
+2. [output.chunkFormat](/config/output#outputchunkformat): Set to `'module'` to use ESM format.
+3. [output.library.type](/config/output#outputlibrarytype): Set to `'modern-module'` for additional optimization of library ESM output format.
+4. [output.chunkLoading](/config/output#outputchunkloading): Set to `'import'` to use ESM `import` for loading chunks.
+5. [output.workerChunkLoading](/config/output#outputworkerchunkloading): Set to `'import'` to use ESM `import` for loading workers.
+6. [optimization.concatenateModules](/config/optimization#optimizationconcatenatemodules): modern-module depends on this option being enabled to ensure the output supports good tree-shaking and correct library exports.
+7. [optimization.avoidEntryIife](/config/optimization#optimizationavoidentryiife): In some cases, Rspack wraps ESM output in an IIFE, which breaks ESM's modular characteristics.
+8. [experiments.outputModule](/config/experiments#experimentsoutputmodule): Enable the experimental feature required for output.module.
+9. [HtmlWebpackPlugin.scriptLoading](/guide/tech/html#htmlwebpackplugin): Set to `'module'` to use ESM `<script type="module">` for loading `.mjs` modules.
diff --git a/website/docs/zh/guide/features/esm.mdx b/website/docs/zh/guide/features/esm.mdx
@@ -2,31 +2,7 @@ import { Stability } from '@components/ApiMeta';
 
 # ESM 格式产物
 
-Rspack 支持打包 ESM 格式的产物。默认情况下，Rspack 会生成类似 CommonJS 格式的产物，但你可以通过配置 `output.module` 来生成 ESM 格式的产物。
-
-下面列出了与 ESM 相关的主要配置选项及其说明，这些配置在构建应用和库时都会用到。
-
-1. [output.module](/config/output#outputmodule): 设置为 `true`，表示生成 ESM 格式的产物。开启此选项后，会对以下配置产生影响：
-   1. 影响 [externalsType](/config/externals#externalstype) 默认值：当 `output.module` 为 `true` 时，`externalsType` 默认为 `'module-import'`
-   2. 影响 [output.filename](/config/output#outputfilename) 默认值：当 `output.module` 为 `true` 时，默认文件名为 `'[name].mjs'` 而不是 `'[name].js'`
-   3. 影响 [output.chunkFilename](/config/output#outputchunkfilename) 默认值：当 `output.module` 为 `true` 时，chunk 文件名默认为 `'[id].mjs'` 而不是 `'[id].js'`
-   4. 影响 [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename) 默认值：当 `output.module` 为 `true` 时，默认为 `'[id].[fullhash].hot-update.mjs'`
-   5. 影响 [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename) 默认值：当 `output.module` 为 `true` 时，默认为 `'[runtime].[fullhash].hot-update.json.mjs'`
-   6. 影响 [output.iife](/config/output#outputiife) 默认值：当 `output.module` 为 `true` 时，`output.iife` 默认为 `false`
-   7. 影响 [output.library.type](/config/output#outputlibrarytype) 默认值：当 `output.module` 为 `true` 时，默认为 `'module'` 而不是 `'var'`
-   8. 影响 [output.scriptType](/config/output#outputscripttype) 默认值：当 `output.module` 为 `true` 时，默认为 `'module'`
-   9. 影响 [output.environment.dynamicImport](/config/output#outputenvironmentdynamicimport) 默认值：当 `output.module` 为 `true` 时会被启用
-   10. 影响 [output.environment.dynamicImportInWorker](/config/output#outputenvironmentdynamicimportinworker) 默认值：当 `output.module` 为 `true` 时会被启用
-   11. 影响 [output.environment.module](/config/output#outputenvironmentmodule) 默认值：当 `output.module` 为 `true` 时会被启用
-   12. 影响 Node.js 相关配置的默认值：在 Node.js 环境下，当 `output.module` 为 `true` 时，`__filename` 和 `__dirname` 默认为 `'node-module'`
-2. [output.chunkFormat](/config/output#outputchunkformat): 设置为 `'module'`，表示使用 ESM 格式。
-3. [output.library.type](/config/output#outputlibrarytype): 设置为 `'modern-module'`，表示对库的 ESM 产物格式进行额外的优化。
-4. [output.chunkLoading](/config/output#outputchunkloading): 设置为 `'import'`，表示使用 ESM 的 `import` 来加载 chunk。
-5. [output.workerChunkLoading](/config/output#outputworkerchunkloading): 设置为 `'import'`，表示使用 ESM 的 `import` 来加载 worker
-6. [optimization.concatenateModules](/config/optimization#optimizationconcatenatemodules): modern-module 依赖此选项的开启来保证输出的产物支持良好的 tree-shaking 和库的正确导出
-7. [optimization.avoidEntryIife](/config/optimization#optimizationavoidentryiife): 在某些情况下，Rspack 会将 ESM 产物的输出包裹在一个 IIFE 中，这会破坏 ESM 的模块化特性
-8. [experiments.outputModule](/config/experiments#experimentsoutputmodule): 开启 output.module 所需的前置实验特性
-9. [HtmlWebpackPlugin.scriptLoading](/guide/tech/html#htmlwebpackplugin): 设置为 `'module'`，表示使用 ESM 的 `<script type="module">` 来加载 `.mjs` 模块。
+Rspack 支持打包 ESM 格式的产物。默认情况下，Rspack 会生成类似 CommonJS 格式的产物，但你可以通过配置 [output.module](/config/output#outputmodule) 来生成 ESM 格式的产物。下面的章节介绍了如何 [构建应用的 ESM 格式产物](#构建应用的-esm-格式产物) 及 [构建库的 ESM 格式产物](#构建库的-esm-格式产物) 并在最后列出了与 ESM 产物相关的 [配置清单](#配置清单)。
 
 ## 构建应用的 ESM 格式产物
 
@@ -93,3 +69,29 @@ export default {
 4. 外部模块的重新导出（`export * from '...'`）在 ESM 格式下无法正确保留
 
 我们正在持续改进 Rspack 的 ESM 支持，致力于提供完善的 ESM 方案，解决现有问题，使 ESM 的使用和配置更加简单直观，更好地拥抱现代 JavaScript 模块系统。
+
+## 配置清单
+
+下面列出了与 ESM 相关的主要配置选项及其说明，这些配置在构建应用和库时都会用到。
+
+1. [output.module](/config/output#outputmodule): 设置为 `true`，表示生成 ESM 格式的产物。开启此选项后，会对以下配置产生影响：
+   1. 影响 [externalsType](/config/externals#externalstype) 默认值：当 `output.module` 为 `true` 时，`externalsType` 默认为 `'module-import'`
+   2. 影响 [output.filename](/config/output#outputfilename) 默认值：当 `output.module` 为 `true` 时，默认文件名为 `'[name].mjs'` 而不是 `'[name].js'`
+   3. 影响 [output.chunkFilename](/config/output#outputchunkfilename) 默认值：当 `output.module` 为 `true` 时，chunk 文件名默认为 `'[id].mjs'` 而不是 `'[id].js'`
+   4. 影响 [output.hotUpdateChunkFilename](/config/output#outputhotupdatechunkfilename) 默认值：当 `output.module` 为 `true` 时，默认为 `'[id].[fullhash].hot-update.mjs'`
+   5. 影响 [output.hotUpdateMainFilename](/config/output#outputhotupdatemainfilename) 默认值：当 `output.module` 为 `true` 时，默认为 `'[runtime].[fullhash].hot-update.json.mjs'`
+   6. 影响 [output.iife](/config/output#outputiife) 默认值：当 `output.module` 为 `true` 时，`output.iife` 默认为 `false`
+   7. 影响 [output.library.type](/config/output#outputlibrarytype) 默认值：当 `output.module` 为 `true` 时，默认为 `'module'` 而不是 `'var'`
+   8. 影响 [output.scriptType](/config/output#outputscripttype) 默认值：当 `output.module` 为 `true` 时，默认为 `'module'`
+   9. 影响 [output.environment.dynamicImport](/config/output#outputenvironmentdynamicimport) 默认值：当 `output.module` 为 `true` 时会被启用
+   10. 影响 [output.environment.dynamicImportInWorker](/config/output#outputenvironmentdynamicimportinworker) 默认值：当 `output.module` 为 `true` 时会被启用
+   11. 影响 [output.environment.module](/config/output#outputenvironmentmodule) 默认值：当 `output.module` 为 `true` 时会被启用
+   12. 影响 Node.js 相关配置的默认值：在 Node.js 环境下，当 `output.module` 为 `true` 时，`__filename` 和 `__dirname` 默认为 `'node-module'`
+2. [output.chunkFormat](/config/output#outputchunkformat): 设置为 `'module'`，表示使用 ESM 格式。
+3. [output.library.type](/config/output#outputlibrarytype): 设置为 `'modern-module'`，表示对库的 ESM 产物格式进行额外的优化。
+4. [output.chunkLoading](/config/output#outputchunkloading): 设置为 `'import'`，表示使用 ESM 的 `import` 来加载 chunk。
+5. [output.workerChunkLoading](/config/output#outputworkerchunkloading): 设置为 `'import'`，表示使用 ESM 的 `import` 来加载 worker
+6. [optimization.concatenateModules](/config/optimization#optimizationconcatenatemodules): modern-module 依赖此选项的开启来保证输出的产物支持良好的 tree-shaking 和库的正确导出
+7. [optimization.avoidEntryIife](/config/optimization#optimizationavoidentryiife): 在某些情况下，Rspack 会将 ESM 产物的输出包裹在一个 IIFE 中，这会破坏 ESM 的模块化特性
+8. [experiments.outputModule](/config/experiments#experimentsoutputmodule): 开启 output.module 所需的前置实验特性
+9. [HtmlWebpackPlugin.scriptLoading](/guide/tech/html#htmlwebpackplugin): 设置为 `'module'`，表示使用 ESM 的 `<script type="module">` 来加载 `.mjs` 模块。
