Skip to content

docs: discourage the use of rspack-chain for custom plugin options #5223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chenjiahan merged 1 commit into from
May 12, 2025
Merged

docs: discourage the use of rspack-chain for custom plugin options #5223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 8 additions & 18 deletions website/docs/en/config/tools/bundler-chain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
28 changes: 16 additions & 12 deletions website/docs/en/guide/configuration/rspack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
},
},
};
Expand All @@ -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.

Expand Down Expand Up @@ -255,7 +253,7 @@ export default {
};
```

#### Configure plugin
#### Custom plugin

Here are examples of adding, modifying, and deleting Rspack plugins.

Expand Down Expand Up @@ -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.
Expand Down
26 changes: 8 additions & 18 deletions website/docs/zh/config/tools/bundler-chain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
28 changes: 16 additions & 12 deletions website/docs/zh/guide/configuration/rspack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
},
},
};
Expand All @@ -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 的示例。

Expand Down Expand Up @@ -257,7 +255,7 @@ export default {
};
```

#### 配置 Plugin
#### 自定义 Plugin

下面是新增、修改和删除 Rspack 插件的示例。

Expand Down Expand Up @@ -287,6 +285,12 @@ export default {
};
```

:::tip
在绝大部分情况下，你应该通过 Rsbuild 提供的配置项来修改插件的选项，而不是通过 `CHAIN_ID.PLUGIN` 来修改，否则可能导致预期之外的行为。

例如，通过 [tools.htmlPlugin](/config/tools/html-plugin) 来修改 HtmlPlugin 的选项。
:::

#### 根据环境修改

在 `tools.bundlerChain` 函数的第二个参数中，你可以拿到各种环境的标识，如开发/生产模式构建、 SSR 构建、Web Worker 构建，从而实现不同环境下的配置修改。
Expand Down
Loading