docs: polish Rule configuration (#8565)

web-infra-dev · Nov 29, 2024 · 245e85e · 245e85e
1 parent d249e62
commit 245e85e
Show file tree

Hide file tree

Showing 2 changed files with 162 additions and 24 deletions.
diff --git a/website/docs/en/config/module.mdx b/website/docs/en/config/module.mdx
@@ -1068,32 +1068,102 @@ For specific generator options and the corresponding module type, you can refer
 
 - **Type:** `boolean`
 
-Flag the module for side effects
+Flag the module for side effects, this will affect the result of [Tree Shaking](/guide/optimization/tree-shaking).
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /foo\.js$/,
+        sideEffects: false,
+      },
+    ],
+  },
+};
+```
 
 ### Rule.enforce
 
 <PropertyType type="'pre' | 'post'" />
 
-Specifies the category of the loader.
+Specifies the category of the loader. When not specified, it defaults to normal loader.
 
-When specified as 'pre', the loader will execute before all other loaders.
+There is also an additional category "inlined loader" which are loaders applied inline of the import/require.
 
-When specified as 'post', the loader will execute after all other loaders.
+When specified as `'pre'`, the loader will execute before all other loaders.
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        enforce: 'pre',
+        loader: 'my-pre-loader',
+      },
+    ],
+  },
+};
+```
+
+When specified as `'post'`, the loader will execute after all other loaders.
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        enforce: 'post',
+        loader: 'my-post-loader',
+      },
+    ],
+  },
+};
+```
+
+There are two phases that all loaders enter one after the other:
+
+- **Pitching phase:** the `pitch` method on loaders is called in the order `post, inline, normal, pre`. See [Pitching Loader](/api/loader-api/examples#pitching-loader) for details.
+- **Normal phase:** the default method on loaders is executed in the order `pre, normal, inline, post`. Transformation on the source code of a module happens in this phase.
 
 ### Rule.type
 
-- **Type:** `'javascript/auto' | 'typescript' | 'css' | 'css/module' | 'css/auto' | 'json' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`
+- **Type:** `'javascript/auto' | 'css' | 'css/module' | 'css/auto' | 'json' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`
+
+Used to mark the type of the matching module, which affects how the module is handled by Rspack's built-in processing.
+
+By default, Rspack will determine the type of the module based on the file extension. For example, `.js` and `.mjs` files will be treated as `javascript/auto` modules, and `.json` files will be treated as `json` modules.
+
+For example, if you want to load a `.json` file through a custom loader, you'd need to set the type to `javascript/auto` to bypass Rspack's built-in JSON importing.
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.json$/,
+        type: 'javascript/auto',
+        loader: 'custom-json-loader',
+      },
+    ],
+  },
+};
+```
 
-Used to mark the type of the matching module, which affects how the module is handled by Rspack's built-in processing. For example, when a module is marked as `'typescript'` then the module is processed using the TS parser/generator.
+All `type` options are as follows:
 
-- `'javascript/auto'`: JavaScript modules, supported module systems: CommonJS, ESM, no plans for AMD module support at this time.
+- `'javascript/auto'`: JavaScript modules, supported module systems: CommonJS, ES modules.
 - `'javascript/esm'`：JavaScript modules, treated as ES modules.
 - `'javascript/dynamic'`：JavaScript modules, treated as Script.
-- `'css'`: CSS module
-- `'css/module'`: CSS Modules module
-- `'css/auto'`: CSS Modules module if filename matches `/\.module(s)?\.[^.]+$/`, otherwise CSS module
-- `'json'`: JSON data module
-- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`: See [Asset Module](/guide/features/asset-module)
+- `'json'`: JSON data module, see [JSON](/guide/tech/json).
+- `'css' | 'css/module' | 'css/auto'`: CSS module, see [Native CSS Support](/guide/tech/css#native-css-support).
+- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`: Asset module, see [Asset Module](/guide/features/asset-module).
 
 ### Rule.layer
 

diff --git a/website/docs/zh/config/module.mdx b/website/docs/zh/config/module.mdx
@@ -1066,32 +1066,100 @@ module.exports = {
 
 - **类型：** `boolean`
 
-标记模块是否存在副作用。
+标记模块是否存在副作用，这会影响 [Tree Shaking](/guide/optimization/tree-shaking) 的结果。
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /foo\.js$/,
+        sideEffects: false,
+      },
+    ],
+  },
+};
+```
 
 ### Rule.enforce
 
 <PropertyType type="'pre' | 'post'" />
 
-指定 loader 的类型。
+指定 loader 的类型，未指定时默认为 normal loader。
+
+当指定为 `'pre'` 时，该 loader 会在其他所有 loader 之前执行。
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        enforce: 'pre',
+        loader: 'my-pre-loader',
+      },
+    ],
+  },
+};
+```
+
+当指定为 `'post'` 时，该 loader 会在其他所有 loader 之后执行。
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.js$/,
+        enforce: 'post',
+        loader: 'my-post-loader',
+      },
+    ],
+  },
+};
+```
 
-当指定为 'pre' 时，该 loader 会在其他所有 loader 之前执行。
+所有 loader 都会进入以下两个阶段：
 
-当指定为 'post' 时，该 loader 会在其他所有 loader 之后执行。
+- **Pitching 阶段:** loader 导出的 `pitch` 方法在 `post, inline, normal, pre` 顺序下被调用。详见 [Pitching Loader](/api/loader-api/examples#pitching-loader)。
+- **Normal 阶段:** loader 导出的默认方法在 `pre, normal, inline, post` 顺序下被执行。模块的源码转换发生在该阶段。
 
 ### Rule.type
 
-- **类型：** `'javascript/auto' | 'typescript' | 'css' | 'css/module' | 'css/auto' | 'json' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline' | 'tsx' | 'jsx'`
+- **类型：** `'javascript/auto' | 'css' | 'css/module' | 'css/auto' | 'json' | 'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`
+
+用于标记匹配的模块的类型，这会影响 Rspack 内置对于该模块的处理方式。
+
+默认情况下，Rspack 会根据文件扩展名来决定模块的类型。例如，`.js` 和 `.mjs` 文件会被当作 `javascript/auto` 模块处理，`.json` 文件会被当作 `json` 模块处理。
+
+例如，如果你想通过一个自定义 Loader 加载 `.json` 文件，你需要将类型设置为 `javascript/auto` 以绕过 Rspack 内置的 JSON 导入。
+
+```js title=rspack.config.js
+module.exports = {
+  // ...
+  module: {
+    rules: [
+      {
+        test: /\.json$/,
+        type: 'javascript/auto',
+        loader: 'custom-json-loader',
+      },
+    ],
+  },
+};
+```
 
-用于标记匹配的模块的类型，这会影响 Rspack 内置对于该模块的处理方式。例如：当模块被标记为 `'typescript'` 则会使用 TS parser/generator 对模块进行处理。
+所有 `type` 如下：
 
-- `'javascript/auto'`：JavaScript 模块，支持的模块系统：CommonJS、ESM，暂没有对 AMD 模块支持的计划。
+- `'javascript/auto'`：JavaScript 模块，支持的模块系统：CommonJS、ES modules。
 - `'javascript/esm'`：JavaScript 模块，当作严格 ES modules 处理。
 - `'javascript/dynamic'`：JavaScript 模块，当作 Script 处理。
-- `'css'`：CSS 模块。
-- `'css/module'`：CSS Modules 模块。
-- `'css/auto'`：基于文件名判断，若匹配`/\.module(s)?\.[^.]+$/`则为 CSS Modules 模块，否则为 CSS 模块。
-- `'json'`：JSON data 模块。
-- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`：参考[资源模块](/guide/features/asset-module)。
+- `'json'`：JSON data 模块，参考 [JSON](/guide/tech/json)。
+- `'css' | 'css/module' | 'css/auto'`：CSS 模块，参考 [原生 CSS 支持](/guide/tech/css#原生-css-支持)。
+- `'asset' | 'asset/source' | 'asset/resource' | 'asset/inline'`：资源模块，参考 [资源模块](/guide/features/asset-module)。
 
 ### Rule.layer