diff --git a/website/docs/en/config/module.mdx b/website/docs/en/config/module.mdx index 9b32600bae5..48092a0ba18 100644 --- 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 -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 index 2c86b36594b..0129f0a4610 100644 --- 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 -指定 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