diff --git a/website/docs/en/config/tools/bundler-chain.mdx b/website/docs/en/config/tools/bundler-chain.mdx index eb56c623c8..d9978a2061 100644 --- a/website/docs/en/config/tools/bundler-chain.mdx +++ b/website/docs/en/config/tools/bundler-chain.mdx @@ -221,29 +221,19 @@ For example, the `RULE.STYLUS` rule exists only when the Stylus plugin is regist `USE.[ID]` can match a certain loader. -| ID | Description | -| ----------------- | -------------------------------------------------------------------------------------- | -| `USE.SWC` | correspond to `builtin:swc-loader` | -| `USE.STYLE` | correspond to `style-loader` | -| `USE.POSTCSS` | correspond to `postcss-loader` | -| `USE.LESS` | correspond to `less-loader` (requires [Less plugin](/plugins/list/plugin-less)) | -| `USE.SASS` | correspond to `sass-loader` (requires [Sass plugin](/plugins/list/plugin-sass)) | -| `USE.RESOLVE_URL` | correspond to `resolve-url-loader` (requires [Sass plugin](/plugins/list/plugin-sass)) | -| `USE.VUE` | correspond to `vue-loader` (requires [Vue plugin](/plugins/list/plugin-vue)) | -| `USE.SVGR` | correspond to `svgr-loader` (requires [Svgr plugin](/plugins/list/plugin-svgr)) | -| `USE.BABEL` | correspond to `babel-loader` (requires [Babel plugin](/plugins/list/plugin-babel)) | -| `USE.SVELTE` | correspond to `svelte-loader` (requires [Svelte plugin](/plugins/list/plugin-svelte)) | -| `USE.STYLUS` | correspond to `stylus-loader` (requires [Stylus plugin](/plugins/list/plugin-stylus)) | +| ID | Description | +| ------------- | ---------------------------------- | +| `USE.SWC` | correspond to `builtin:swc-loader` | +| `USE.STYLE` | correspond to `style-loader` | +| `USE.POSTCSS` | correspond to `postcss-loader` | + +See [Custom loader](/guide/configuration/rspack#custom-loader) for more details. ### CHAIN_ID.PLUGIN `PLUGIN.[ID]` can match a certain Rspack or webpack plugin. -| ID | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `PLUGIN.HTML` | correspond to [HtmlRspackPlugin](https://rspack.dev/plugins/rspack/html-rspack-plugin), you need to concat the entry name when using: `${PLUGIN.HTML}-${entryName}` | -| `PLUGIN.SUBRESOURCE_INTEGRITY` | correspond to [SubresourceIntegrityPlugin](https://rspack.dev/plugins/rspack/subresource-integrity-plugin) | -| `PLUGIN.BUNDLE_ANALYZER` | correspond to [BundleAnalyzerPlugin](https://github.com/webpack-contrib/webpack-bundle-analyzer) | +See [Custom plugin](/guide/configuration/rspack#custom-plugin) for more details. ### CHAIN_ID.MINIMIZER diff --git a/website/docs/en/guide/configuration/rspack.mdx b/website/docs/en/guide/configuration/rspack.mdx index b7df9db942..930243dc70 100644 --- a/website/docs/en/guide/configuration/rspack.mdx +++ b/website/docs/en/guide/configuration/rspack.mdx @@ -122,14 +122,13 @@ In short, the rspack-chain requires users to set a unique ID for each rule, load Rsbuild exports all internally defined IDs through the `CHAIN_ID` object, so you can quickly locate the loader or plugin you want to modify using these exported IDs, without the need for complex traversal in the Rspack configuration object. -For example, you can remove the built-in HTML plugin using `CHAIN_ID.PLUGIN.HTML`: +For example, you can remove the built-in CSS rule using `CHAIN_ID.RULE.CSS`: ```ts title="rsbuild.config.ts" export default { tools: { bundlerChain: (chain, { CHAIN_ID }) => { - // - chain.plugins.delete(CHAIN_ID.PLUGIN.HTML); + chain.module.rules.delete(CHAIN_ID.RULE.CSS); }, }, }; @@ -139,17 +138,16 @@ export default { The `CHAIN_ID` object contains various IDs, which correspond to the following configurations: -| CHAIN_ID Field | Corresponding Configuration | Description | -| ------------------------- | --------------------------- | ----------------------------------------------------------- | -| `CHAIN_ID.PLUGIN` | `plugins[i]` | Corresponds to a plugin in the Rspack configuration | -| `CHAIN_ID.RULE` | `module.rules[i]` | Corresponds to a rule in the Rspack configuration | -| `CHAIN_ID.USE` | `module.rules[i].loader` | Corresponds to a loader in the Rspack configuration | -| `CHAIN_ID.MINIMIZER` | `optimization.minimizer` | Corresponds to a minimizer in the Rspack configuration | -| `CHAIN_ID.RESOLVE_PLUGIN` | `resolve.plugins[i]` | Corresponds to a resolve plugin in the Rspack configuration | +| CHAIN_ID Field | Corresponding Configuration | Description | +| -------------------- | --------------------------- | ------------------------------------------------------ | +| `CHAIN_ID.PLUGIN` | `plugins[i]` | Corresponds to a plugin in the Rspack configuration | +| `CHAIN_ID.RULE` | `module.rules[i]` | Corresponds to a rule in the Rspack configuration | +| `CHAIN_ID.USE` | `module.rules[i].loader` | Corresponds to a loader in the Rspack configuration | +| `CHAIN_ID.MINIMIZER` | `optimization.minimizer` | Corresponds to a minimizer in the Rspack configuration | ### Examples -#### Configure loader +#### Custom loader Here are examples of adding, modifying, and removing Rspack loaders. @@ -255,7 +253,7 @@ export default { }; ``` -#### Configure plugin +#### Custom plugin Here are examples of adding, modifying, and deleting Rspack plugins. @@ -285,6 +283,12 @@ export default { }; ``` +:::tip +In most cases, you should change the plugin options using the configurations provided by Rsbuild, rather than using `CHAIN_ID.PLUGIN`, as this may lead to unexpected behavior. + +For example, use [tools.htmlPlugin](/config/tools/html-plugin) to change the options of HtmlPlugin. +::: + #### Modify based on environment In the `tools.bundlerChain` function, you can access various environment identifiers in the second parameter, such as development/production build, SSR build, Web Worker build, to achieve configuration modifications for different environments. diff --git a/website/docs/zh/config/tools/bundler-chain.mdx b/website/docs/zh/config/tools/bundler-chain.mdx index 2ba50ea647..aa286066cc 100644 --- a/website/docs/zh/config/tools/bundler-chain.mdx +++ b/website/docs/zh/config/tools/bundler-chain.mdx @@ -220,29 +220,19 @@ Rsbuild 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 通过 `USE.[ID]` 可以匹配到对应的 loader。 -| ID | 描述 | -| ----------------- | ------------------------------------------------------------------------ | -| `USE.SWC` | 对应 `builtin:swc-loader` | -| `USE.POSTCSS` | 对应 `postcss-loader` | -| `USE.STYLE` | 对应 `style-loader` | -| `USE.LESS` | 对应 `less-loader`（依赖 [Less 插件](/plugins/list/plugin-less)） | -| `USE.SASS` | 对应 `sass-loader`（依赖 [Sass 插件](/plugins/list/plugin-sass)） | -| `USE.RESOLVE_URL` | 对应 `resolve-url-loader`（依赖 [Sass 插件](/plugins/list/plugin-sass)） | -| `USE.VUE` | 对应 `vue-loader`（依赖 [Vue 插件](/plugins/list/plugin-vue)） | -| `USE.SVGR` | 对应 `svgr-loader`（依赖 [Svgr 插件](/plugins/list/plugin-svgr)） | -| `USE.BABEL` | 对应 `babel-loader`（依赖 [Babel 插件](/plugins/list/plugin-babel)） | -| `USE.SVELTE` | 对应 `svelte-loader`（依赖 [Svelte 插件](/plugins/list/plugin-svelte)） | -| `USE.STYLUS` | 对应 `stylus-loader`（依赖 [Stylus 插件](/plugins/list/plugin-stylus)） | +| ID | 描述 | +| ------------- | ------------------------- | +| `USE.SWC` | 对应 `builtin:swc-loader` | +| `USE.POSTCSS` | 对应 `postcss-loader` | +| `USE.STYLE` | 对应 `style-loader` | + +详见 [自定义 loader](/guide/configuration/rspack#自定义-loader) ### CHAIN_ID.PLUGIN 通过 `PLUGIN.[ID]` 可以匹配到特定的 Rspack 或 webpack plugin。 -| ID | 描述 | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `PLUGIN.HTML` | 对应 [HtmlRspackPlugin](https://rspack.dev/zh/plugins/rspack/html-rspack-plugin)，使用时需要拼接 entry 名称：`${PLUGIN.HTML}-${entryName}` | -| `PLUGIN.SUBRESOURCE_INTEGRITY` | 对应 [SubresourceIntegrityPlugin](https://rspack.dev/zh/plugins/rspack/subresource-integrity-plugin) | -| `PLUGIN.BUNDLE_ANALYZER` | 对应 [BundleAnalyzerPlugin](https://github.com/webpack-contrib/webpack-bundle-analyzer) | +详见 [自定义 Plugin](/guide/configuration/rspack#自定义-plugin) ### CHAIN_ID.MINIMIZER diff --git a/website/docs/zh/guide/configuration/rspack.mdx b/website/docs/zh/guide/configuration/rspack.mdx index 56e283dd8b..274cea7c64 100644 --- a/website/docs/zh/guide/configuration/rspack.mdx +++ b/website/docs/zh/guide/configuration/rspack.mdx @@ -124,14 +124,13 @@ export default { Rsbuild 将内部定义的全部 id 都通过 `CHAIN_ID` 对象导出，因此你可以通过这些导出的 id，快速定位到你想要修改的 Loader 或 Plugin，而不需要在 Rspack 配置对象里通过复杂的遍历寻找。 -比如通过 `CHAIN_ID.PLUGIN.HTML` 来删除内置的 HTML 插件： +比如通过 `CHAIN_ID.RULE.CSS` 来删除内置的 CSS 处理规则： ```ts title="rsbuild.config.ts" export default { tools: { bundlerChain: (chain, { CHAIN_ID }) => { - // - chain.plugins.delete(CHAIN_ID.PLUGIN.HTML); + chain.module.rules.delete(CHAIN_ID.RULE.CSS); }, }, }; @@ -141,17 +140,16 @@ export default { `CHAIN_ID` 对象包含了多种 id，对应的含义如下： -| CHAIN_ID 字段 | 对应的配置 | 描述 | -| ------------------------- | ------------------------ | ------------------------------------- | -| `CHAIN_ID.PLUGIN` | `plugins[i]` | 对应 Rspack 配置中的一个插件 | -| `CHAIN_ID.RULE` | `module.rules[i]` | 对应 Rspack 配置中的一个 Rule | -| `CHAIN_ID.USE` | `module.rules[i].loader` | 对应 Rspack 配置中的一个 Loader | -| `CHAIN_ID.MINIMIZER` | `optimization.minimizer` | 对应 Rspack 配置中的一个压缩工具 | -| `CHAIN_ID.RESOLVE_PLUGIN` | `resolve.plugins[i]` | 对应 Rspack 配置中的一个 Resolve 插件 | +| CHAIN_ID 字段 | 对应的配置 | 描述 | +| -------------------- | ------------------------ | -------------------------------- | +| `CHAIN_ID.PLUGIN` | `plugins[i]` | 对应 Rspack 配置中的一个插件 | +| `CHAIN_ID.RULE` | `module.rules[i]` | 对应 Rspack 配置中的一个 Rule | +| `CHAIN_ID.USE` | `module.rules[i].loader` | 对应 Rspack 配置中的一个 Loader | +| `CHAIN_ID.MINIMIZER` | `optimization.minimizer` | 对应 Rspack 配置中的一个压缩工具 | ### 示例 -#### 配置 loader +#### 自定义 loader 下面是新增、修改和删除 Rspack loader 的示例。 @@ -257,7 +255,7 @@ export default { }; ``` -#### 配置 Plugin +#### 自定义 Plugin 下面是新增、修改和删除 Rspack 插件的示例。 @@ -287,6 +285,12 @@ export default { }; ``` +:::tip +在绝大部分情况下，你应该通过 Rsbuild 提供的配置项来修改插件的选项，而不是通过 `CHAIN_ID.PLUGIN` 来修改，否则可能导致预期之外的行为。 + +例如，通过 [tools.htmlPlugin](/config/tools/html-plugin) 来修改 HtmlPlugin 的选项。 +::: + #### 根据环境修改 在 `tools.bundlerChain` 函数的第二个参数中，你可以拿到各种环境的标识，如开发/生产模式构建、 SSR 构建、Web Worker 构建，从而实现不同环境下的配置修改。