docs(builder): improve the usage of bundlerChain (#4643)

web-infra-dev · Sep 14, 2023 · 819afc5 · 819afc5
1 parent b351278
commit 819afc5
Show file tree

Hide file tree

Showing 19 changed files with 151 additions and 221 deletions.
diff --git a/packages/document/builder-doc/docs/en/config/output/disableInlineRuntimeChunk.md b/packages/document/builder-doc/docs/en/config/output/disableInlineRuntimeChunk.md
@@ -32,10 +32,8 @@ If you don't want to generate a separate runtimeChunk file, but want the runtime
 ```js
 export default {
   tools: {
-    webpack: {
-      optimization: {
-        runtimeChunk: false,
-      },
+    bundlerChain(chain) {
+      chain.optimization.runtimeChunk(false);
     },
   },
 };

diff --git a/packages/document/builder-doc/docs/en/config/tools/bundlerChain.mdx b/packages/document/builder-doc/docs/en/config/tools/bundlerChain.mdx
@@ -125,18 +125,25 @@ export default {
 
 Some common Chain IDs are predefined in the Builder, and you can use these IDs to locate the built-in Rule or Plugin.
 
+:::tip
+Please note that some of the rules or plugins listed below are not available by default. They will only be included in the Rspack or webpack configuration when you enable specific options or register certain plugins.
+
+For example, the `RULE.STYLUS` rule exists only when the Stylus plugin is registered.
+:::
+
 ##### CHAIN_ID.RULE
 
-| ID          | Description     |
-| ----------- | --------------- |
-| `RULE.MJS`  | Rule for `mjs`  |
-| `RULE.CSS`  | Rule for `css`  |
-| `RULE.LESS` | Rule for `less` |
-| `RULE.SASS` | Rule for `sass` |
-| `RULE.TOML` | Rule for `toml` |
-| `RULE.YAML` | Rule for `yaml` |
-| `RULE.WASM` | Rule for `WASM` |
-| `RULE.NODE` | Rule for `node` |
+| ID            | Description       |
+| ------------- | ----------------- |
+| `RULE.MJS`    | Rule for `mjs`    |
+| `RULE.CSS`    | Rule for `css`    |
+| `RULE.LESS`   | Rule for `less`   |
+| `RULE.SASS`   | Rule for `sass`   |
+| `RULE.STYLUS` | Rule for `stylus` |
+| `RULE.TOML`   | Rule for `toml`   |
+| `RULE.YAML`   | Rule for `yaml`   |
+| `RULE.WASM`   | Rule for `WASM`   |
+| `RULE.NODE`   | Rule for `node`   |
 
 ### CHAIN_ID.ONE_OF
 
@@ -157,6 +164,8 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | --------------------------------- | ---------------------------------- |
 | `USE.LESS`                        | correspond to `less-loader`        |
 | `USE.SASS`                        | correspond to `sass-loader`        |
+| `USE.STYLUS`                      | correspond to `stylus-loader`      |
+| `USE.VUE`                         | correspond to `vue-loader`         |
 | `USE.TOML`                        | correspond to `toml-loader`        |
 | `USE.YAML`                        | correspond to `yaml-loader`        |
 | `USE.NODE`                        | correspond to `node-loader`        |
@@ -175,8 +184,18 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | `PLUGIN.INLINE_HTML`        | correspond to `InlineChunkHtmlPlugin`                                                                   |
 | `PLUGIN.BUNDLE_ANALYZER`    | correspond to `WebpackBundleAnalyzer`                                                                   |
 | `PLUGIN.BOTTOM_TEMPLATE`    | correspond to `BottomTemplatePlugin`                                                                    |
+| `PLUGIN.VUE_LOADER_PLUGIN`  | correspond to `VueLoaderPlugin`                                                                         |
 | `PLUGIN.AUTO_SET_ROOT_SIZE` | correspond to automatically set root font size plugin in Builder                                        |
 
+### CHAIN_ID.MINIMIZER
+
+`MINIMIZER.XXX` can match a certain minimizer.
+
+| ID              | Description                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `MINIMIZER.JS`  | correspond to `TerserWebpackPlugin` or `SwcJsMinimizerRspackPlugin` |
+| `MINIMIZER.CSS` | correspond to `CssMinimizerWebpackPlugin`                           |
+
 ### Examples
 
-The usage of BundlerChain can reference: [WebpackChain Examples](https://modernjs.dev/builder/en/guide/advanced/custom-webpack-config.html#webpack-chain-basics).
+For usage examples, please refer to: [WebpackChain usage examples](https://modernjs.dev/builder/en/guide/advanced/custom-webpack-config.html#webpack-chain-basics).
diff --git a/packages/document/builder-doc/docs/en/config/tools/webpack.md b/packages/document/builder-doc/docs/en/config/tools/webpack.md
@@ -4,7 +4,7 @@
 
 `tools.webpack` is used to configure [webpack](https://webpack.js.org/).
 
-> `tools.webpackChain` is also used to modify the webpack configuration, and the function is more powerful. It is recommended to use `tools.webpackChain` first.
+> `tools.bundlerChain` is also used to modify the webpack configuration, and the function is more powerful. It is recommended to use `tools.bundlerChain` first.
 
 ### Object Type
 
@@ -170,7 +170,7 @@ The HtmlWebpackPlugin instance:
 ```js
 export default {
   tools: {
-    webpackChain: (chain, { HtmlWebpackPlugin }) => {
+    webpack: (chain, { HtmlWebpackPlugin }) => {
       console.log(HtmlWebpackPlugin);
     },
   },

diff --git a/packages/document/builder-doc/docs/en/config/tools/webpackChain.md b/packages/document/builder-doc/docs/en/config/tools/webpackChain.md
@@ -169,27 +169,34 @@ export default {
 
 Some common Chain IDs are predefined in the Builder, and you can use these IDs to locate the built-in Rule or Plugin.
 
-##### CHAIN_ID.RULE
-
-| ID           | Description      |
-| ------------ | ---------------- |
-| `RULE.MJS`   | Rule for `mjs`   |
-| `RULE.JS`    | Rule for `js`    |
-| `RULE.TS`    | Rule for `ts`    |
-| `RULE.CSS`   | Rule for `css`   |
-| `RULE.LESS`  | Rule for `less`  |
-| `RULE.SASS`  | Rule for `sass`  |
-| `RULE.PUG`   | Rule for `pug`   |
-| `RULE.VUE`   | Rule for `vue`   |
-| `RULE.TOML`  | Rule for `toml`  |
-| `RULE.YAML`  | Rule for `yaml`  |
-| `RULE.WASM`  | Rule for `WASM`  |
-| `RULE.NODE`  | Rule for `node`  |
-| `RULE.FONT`  | Rule for `font`  |
-| `RULE.IMAGE` | Rule for `image` |
-| `RULE.MEDIA` | Rule for `media` |
-
-### CHAIN_ID.ONE_OF
+:::tip
+Please note that some of the rules or plugins listed below are not available by default. They will only be included in the webpack configuration when you enable specific options or register certain plugins.
+
+For example, the `RULE.STYLUS` rule exists only when the Stylus plugin is registered.
+:::
+
+#### CHAIN_ID.RULE
+
+| ID            | Description       |
+| ------------- | ----------------- |
+| `RULE.MJS`    | Rule for `mjs`    |
+| `RULE.JS`     | Rule for `js`     |
+| `RULE.TS`     | Rule for `ts`     |
+| `RULE.CSS`    | Rule for `css`    |
+| `RULE.LESS`   | Rule for `less`   |
+| `RULE.SASS`   | Rule for `sass`   |
+| `RULE.STYLUS` | Rule for `stylus` |
+| `RULE.PUG`    | Rule for `pug`    |
+| `RULE.VUE`    | Rule for `vue`    |
+| `RULE.TOML`   | Rule for `toml`   |
+| `RULE.YAML`   | Rule for `yaml`   |
+| `RULE.WASM`   | Rule for `WASM`   |
+| `RULE.NODE`   | Rule for `node`   |
+| `RULE.FONT`   | Rule for `font`   |
+| `RULE.IMAGE`  | Rule for `image`  |
+| `RULE.MEDIA`  | Rule for `media`  |
+
+#### CHAIN_ID.ONE_OF
 
 `ONE_OF.XXX` can match a certain type of rule in the rule array.
 
@@ -200,7 +207,7 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | `ONE_OF.SVG_INLINE` | Rules for SVG, inlined into bundles as data URIs                   |
 | `ONE_OF.SVG_ASSETS` | Rules for SVG, automatic choice between data URI and separate file |
 
-### CHAIN_ID.USE
+#### CHAIN_ID.USE
 
 `USE.XXX` can match a certain loader.
 
@@ -210,6 +217,7 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | `USE.CSS`                         | correspond to `css-loader`                     |
 | `USE.LESS`                        | correspond to `less-loader`                    |
 | `USE.SASS`                        | correspond to `sass-loader`                    |
+| `USE.STYLUS`                      | correspond to `stylus-loader`                  |
 | `USE.PUG`                         | correspond to `pug-loader`                     |
 | `USE.VUE`                         | correspond to `vue-loader`                     |
 | `USE.TOML`                        | correspond to `toml-loader`                    |
@@ -221,12 +229,11 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | `USE.BABEL`                       | correspond to `babel-loader`                   |
 | `USE.STYLE`                       | correspond to `style-loader`                   |
 | `USE.POSTCSS`                     | correspond to `postcss-loader`                 |
-| `USE.MARKDOWN`                    | correspond to `markdown-loader`                |
 | `USE.CSS_MODULES_TS`              | correspond to `css-modules-typescript-loader`  |
 | `USE.MINI_CSS_EXTRACT`            | correspond to `mini-css-extract-plugin.loader` |
 | `USE.RESOLVE_URL_LOADER_FOR_SASS` | correspond to `resolve-url-loader`             |
 
-### CHAIN_ID.PLUGIN
+#### CHAIN_ID.PLUGIN
 
 `PLUGIN.XXX` can match a certain webpack plugin.
 
@@ -255,7 +262,7 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 | `PLUGIN.ASSETS_RETRY`          | correspond to webpack static asset retry plugin in Builder                                                     |
 | `PLUGIN.AUTO_SET_ROOT_SIZE`    | correspond to automatically set root font size plugin in Builder                                               |
 
-### CHAIN_ID.MINIMIZER
+#### CHAIN_ID.MINIMIZER
 
 `MINIMIZER.XXX` can match a certain minimizer.
 
@@ -268,61 +275,4 @@ Some common Chain IDs are predefined in the Builder, and you can use these IDs t
 
 ### Examples
 
-The following are some common configuration examples, see the full webpack-chain API [webpack-chain documentation](https://github.com/neutrinojs/webpack-chain).
-
-#### Add/Modify/Delete loader
-
-```js
-export default {
-  tools: {
-    webpackChain: (chain, { CHAIN_ID }) => {
-      // Add loader
-      chain.module
-        .rule('md')
-        .test(/\.md$/)
-        .use('md-loader')
-        .loader('md-loader');
-
-      // Modify loader
-      chain.module
-        .rule(CHAIN_ID.RULE.JS)
-        .use(CHAIN_ID.USE.BABEL)
-        .tap(options => {
-          options.plugins.push('babel-plugin-xxx');
-          return options;
-        });
-
-      // Delete loader
-      chain.module.rule(CHAIN_ID.RULE.JS).uses.delete(CHAIN_ID.USE.BABEL);
-    },
-  },
-};
-```
-
-#### Add/Modify/Delete plugin
-
-```js
-export default {
-  tools: {
-    webpackChain: (chain, { webpack, CHAIN_ID }) => {
-      // Add plugin
-      chain.plugin('custom-define').use(webpack.DefinePlugin, [
-        {
-          'process.env': {
-            NODE_ENV: JSON.stringify(process.env.NODE_ENV),
-          },
-        },
-      ]);
-
-      // Modify plugin
-      chain.plugin(CHAIN_ID.PLUGIN.HMR).tap(options => {
-        options[0].fullBuildTimeout = 200;
-        return options;
-      });
-
-      // Delete plugin
-      chain.plugins.delete(CHAIN_ID.PLUGIN.HMR);
-    },
-  },
-};
-```
+For usage examples, please refer to: [WebpackChain usage examples](https://modernjs.dev/builder/en/guide/advanced/custom-webpack-config.html#webpack-chain-basics).
diff --git a/packages/document/builder-doc/docs/en/guide/faq/features.md b/packages/document/builder-doc/docs/en/guide/faq/features.md
@@ -31,7 +31,7 @@ import ESLintPlugin from 'eslint-webpack-plugin';
 
 export default {
   tools: {
-    webpackChain(chain) {
+    bundlerChain(chain) {
       chain.plugin('eslint-plugin').use(ESLintPlugin, [
         {
           extensions: ['.js', '.ts', '.jsx', 'tsx', '.mjs'],

diff --git a/packages/document/builder-doc/docs/en/guide/optimization/build-performance.mdx b/packages/document/builder-doc/docs/en/guide/optimization/build-performance.mdx
@@ -108,7 +108,7 @@ For example to disable Source Map:
 ```js
 export default {
   tools: {
-    webpackChain(chain, { env }) {
+    bundlerChain(chain, { env }) {
       if (env === 'development') {
         chain.devtool(false);
       }
@@ -122,7 +122,7 @@ Or set the source map format of the development environment to the cheapest `eva
 ```js
 export default {
   tools: {
-    webpackChain(chain, { env }) {
+    bundlerChain(chain, { env }) {
       if (env === 'development') {
         chain.devtool('eval');
       }

diff --git a/packages/document/builder-doc/docs/zh/config/output/disableInlineRuntimeChunk.md b/packages/document/builder-doc/docs/zh/config/output/disableInlineRuntimeChunk.md
@@ -32,10 +32,8 @@ export default {
 ```js
 export default {
   tools: {
-    webpack: {
-      optimization: {
-        runtimeChunk: false,
-      },
+    bundlerChain(chain) {
+      chain.optimization.runtimeChunk(false);
     },
   },
 };

diff --git a/packages/document/builder-doc/docs/zh/config/tools/bundlerChain.mdx b/packages/document/builder-doc/docs/zh/config/tools/bundlerChain.mdx
@@ -128,18 +128,25 @@ export default {
 
 Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
 
+:::tip
+请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。
+
+比如，`RULE.STYLUS` 仅在注册了 Stylus 插件后才会存在。
+:::
+
 ##### CHAIN_ID.RULE
 
-| ID          | 描述               |
-| ----------- | ------------------ |
-| `RULE.MJS`  | 处理 `mjs` 的规则  |
-| `RULE.CSS`  | 处理 `css` 的规则  |
-| `RULE.LESS` | 处理 `less` 的规则 |
-| `RULE.SASS` | 处理 `sass` 的规则 |
-| `RULE.TOML` | 处理 `toml` 的规则 |
-| `RULE.YAML` | 处理 `yaml` 的规则 |
-| `RULE.WASM` | 处理 `wasm` 的规则 |
-| `RULE.NODE` | 处理 `node` 的规则 |
+| ID            | 描述                 |
+| ------------- | -------------------- |
+| `RULE.MJS`    | 处理 `mjs` 的规则    |
+| `RULE.CSS`    | 处理 `css` 的规则    |
+| `RULE.LESS`   | 处理 `less` 的规则   |
+| `RULE.SASS`   | 处理 `sass` 的规则   |
+| `RULE.STYLUS` | 处理 `stylus` 的规则 |
+| `RULE.TOML`   | 处理 `toml` 的规则   |
+| `RULE.YAML`   | 处理 `yaml` 的规则   |
+| `RULE.WASM`   | 处理 `wasm` 的规则   |
+| `RULE.NODE`   | 处理 `node` 的规则   |
 
 ### CHAIN_ID.ONE_OF
 
@@ -160,6 +167,8 @@ Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID
 | --------------------------------- | ------------------------- |
 | `USE.LESS`                        | 对应 `less-loader`        |
 | `USE.SASS`                        | 对应 `sass-loader`        |
+| `USE.STYLUS`                      | 对应 `stylus-loader`      |
+| `USE.VUE`                         | 对应 `vue-loader`         |
 | `USE.TOML`                        | 对应 `toml-loader`        |
 | `USE.YAML`                        | 对应 `yaml-loader`        |
 | `USE.NODE`                        | 对应 `node-loader`        |
@@ -179,8 +188,18 @@ Builder 中预先定义了一些常用的 Chain ID，你可以通过这些 ID
 | `PLUGIN.BUNDLE_ANALYZER`    | 对应 `WebpackBundleAnalyzer`                                                |
 | `PLUGIN.BOTTOM_TEMPLATE`    | 对应 `BottomTemplatePlugin`                                                 |
 | `PLUGIN.ASSETS_RETRY`       | 对应 Builder 中的 webpack 静态资源重试插件 `WebpackAssetsRetryPlugin`       |
+| `PLUGIN.VUE_LOADER_PLUGIN`  | 对应 `VueLoaderPlugin`                                                      |
 | `PLUGIN.AUTO_SET_ROOT_SIZE` | 对应 Builder 中的自动设置根字体大小插件 `AutoSetRootSizePlugin`             |
 
-### 常用 BundlerChain 使用示例
+### CHAIN_ID.MINIMIZER
+
+通过 `MINIMIZER.XXX` 可以匹配到对应的压缩工具。
+
+| ID              | 描述                                                       |
+| --------------- | ---------------------------------------------------------- |
+| `MINIMIZER.JS`  | 对应 `TerserWebpackPlugin` 或 `SwcJsMinimizerRspackPlugin` |
+| `MINIMIZER.CSS` | 对应 `CssMinimizerWebpackPlugin`                           |
+
+### 使用示例
 
-BundlerChain 的使用可参考：[常用 WebpackChain 使用示例](https://modernjs.dev/builder/guide/advanced/custom-webpack-config.html#%E4%BD%BF%E7%94%A8-webpack-chain)。
+使用示例可参考：[WebpackChain 使用示例](https://modernjs.dev/builder/guide/advanced/custom-webpack-config.html#%E4%BD%BF%E7%94%A8-webpack-chain)。
diff --git a/packages/document/builder-doc/docs/zh/config/tools/webpack.md b/packages/document/builder-doc/docs/zh/config/tools/webpack.md
@@ -4,7 +4,7 @@
 
 `tools.webpack` 选项用于配置原生的 [webpack](https://webpack.js.org/)。
 
-> `tools.webpackChain` 同样可以修改 webpack 配置，并且功能更加强大，建议优先使用 `tools.webpackChain`。
+> `tools.bundlerChain` 同样可以修改 webpack 配置，并且功能更加强大，建议优先使用 `tools.bundlerChain`。
 
 ### Object 类型
 
@@ -170,7 +170,7 @@ export default {
 ```js
 export default {
   tools: {
-    webpackChain: (chain, { HtmlWebpackPlugin }) => {
+    webpack: (chain, { HtmlWebpackPlugin }) => {
       console.log(HtmlWebpackPlugin);
     },
   },