@modern-js/main-doc 2.59.0 → 2.60.1-alpha.0

package/docs/zh/configure/app/tools/webpack-chain.mdx

@@ -4,6 +4,247 @@ title: webpackChain
 
 # tools.webpackChain
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpackChain.md';
+- **类型：** `Function | undefined`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+你可以通过 `tools.webpackChain` 来修改默认的 webpack 配置，它的值为 `Function` 类型，接收两个参数：
+
+- 第一个参数为 `webpack-chain` 对象实例，你可以通过这个实例来修改默认的 webpack 配置。
+- 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。
+
+相比于 `tools.webpack`，**webpack-chain 不仅支持链式调用，而且能够基于别名来定位到内置的 Rule 或 Plugin，从而实现精准的配置修改**。我们推荐使用 `tools.webpackChain` 来代替 `tools.webpack`。
+
+> `tools.webpackChain` 的执行时机早于 tools.webpack，因此会被 `tools.webpack` 中的修改所覆盖。
+
+### 工具集合
+
+#### env
+
+- **类型：** `'development' | 'production' | 'test'`
+
+通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { env }) => {
+      if (env === 'development') {
+        chain.devtool('cheap-module-eval-source-map');
+      }
+    },
+  },
+};
+```
+
+#### isProd
+
+- **类型：** `boolean`
+
+通过 isProd 参数可以判断当前环境是否为 production。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isProd }) => {
+      if (isProd) {
+        chain.devtool('source-map');
+      }
+    },
+  },
+};
+```
+
+#### target
+
+- **类型：** `'web' | 'node' | 'modern-web' | 'web-worker'`
+
+通过 target 参数可以判断当前构建的目标运行时环境。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { target }) => {
+      if (target === 'node') {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isServer
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isServer }) => {
+      if (isServer) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### isWebWorker
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { isWebWorker }) => {
+      if (isWebWorker) {
+        // ...
+      }
+    },
+  },
+};
+```
+
+#### webpack
+
+- **类型：** `typeof import('webpack')`
+
+通过这个参数你可以拿到 webpack 实例。比如：
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { webpack }) => {
+      chain.plugin('my-progress').use(webpack.ProgressPlugin);
+    },
+  },
+};
+```
+
+#### HtmlWebpackPlugin
+
+- **类型：** `typeof import('html-webpack-plugin')`
+
+通过这个参数你可以拿到 HtmlWebpackPlugin 实例。
+
+```js
+export default {
+  tools: {
+    webpackChain: (chain, { HtmlWebpackPlugin }) => {
+      console.log(HtmlWebpackPlugin);
+    },
+  },
+};
+```
+
+#### CHAIN_ID
+
+Modern.js 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。
+
+:::tip
+请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 webpack 配置中。
+
+比如，`RULE.STYLUS` 仅在注册了 Stylus 插件后才会存在。
+:::
+
+#### CHAIN_ID.RULE
+
+| ID            | 描述                                                                                          |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `RULE.MJS`    | 处理 `mjs` 的规则                                                                             |
+| `RULE.JS`     | 处理 `js` 的规则                                                                              |
+| `RULE.TS`     | 处理 `ts` 的规则                                                                              |
+| `RULE.CSS`    | 处理 `css` 的规则                                                                             |
+| `RULE.LESS`   | 处理 `less` 的规则                                                                            |
+| `RULE.SASS`   | 处理 `sass` 的规则                                                                            |
+| `RULE.STYLUS` | 处理 `stylus` 的规则（依赖 [Stylus 插件](https://rsbuild.dev/zh/plugins/list/plugin-stylus)） |
+| `RULE.SVG`    | Rule for `svg`                                                                                |
+| `RULE.PUG`    | 处理 `pug` 的规则                                                                             |
+| `RULE.TOML`   | 处理 `toml` 的规则                                                                            |
+| `RULE.YAML`   | 处理 `yaml` 的规则                                                                            |
+| `RULE.WASM`   | 处理 `wasm` 的规则                                                                            |
+| `RULE.NODE`   | 处理 `node` 的规则                                                                            |
+| `RULE.FONT`   | 处理字体的规则                                                                                |
+| `RULE.IMAGE`  | 处理图片的规则                                                                                |
+| `RULE.MEDIA`  | 处理媒体资源的规则                                                                            |
+
+#### CHAIN_ID.ONE_OF
+
+通过 `ONE_OF.XXX` 可以匹配到规则数组中的某一类规则。
+
+| ID                  | 描述                                                |
+| ------------------- | --------------------------------------------------- |
+| `ONE_OF.SVG`        | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |
+| `ONE_OF.SVG_URL`    | 处理 SVG 的规则，输出为单独文件                     |
+| `ONE_OF.SVG_INLINE` | 处理 SVG 的规则，作为 data URI 内联到 bundle 中     |
+| `ONE_OF.SVG_ASSETS` | 处理 SVG 的规则，在 data URI 和单独文件之间自动选择 |
+
+#### CHAIN_ID.USE
+
+通过 `USE.XXX` 可以匹配到对应的 loader。
+
+| ID                                | 描述                                  |
+| --------------------------------- | ------------------------------------- |
+| `USE.TS`                          | 对应 `ts-loader`                      |
+| `USE.CSS`                         | 对应 `css-loader`                     |
+| `USE.LESS`                        | 对应 `less-loader`                    |
+| `USE.SASS`                        | 对应 `sass-loader`                    |
+| `USE.STYLUS`                      | 对应 `stylus-loader`                  |
+| `USE.PUG`                         | 对应 `pug-loader`                     |
+| `USE.VUE`                         | 对应 `vue-loader`                     |
+| `USE.TOML`                        | 对应 `toml-loader`                    |
+| `USE.YAML`                        | 对应 `yaml-loader`                    |
+| `USE.NODE`                        | 对应 `node-loader`                    |
+| `USE.URL`                         | 对应 `url-loader`                     |
+| `USE.SVGR`                        | 对应 `@svgr/webpack`                  |
+| `USE.BABEL`                       | 对应 `babel-loader`                   |
+| `USE.STYLE`                       | 对应 `style-loader`                   |
+| `USE.POSTCSS`                     | 对应 `postcss-loader`                 |
+| `USE.CSS_MODULES_TS`              | 对应 `css-modules-typescript-loader`  |
+| `USE.MINI_CSS_EXTRACT`            | 对应 `mini-css-extract-plugin.loader` |
+| `USE.RESOLVE_URL_LOADER_FOR_SASS` | 对应 `resolve-url-loader`             |
+
+#### CHAIN_ID.PLUGIN
+
+通过 `PLUGIN.XXX` 可以匹配到对应的 plugin。
+
+| ID                             | 描述                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------- |
+| `PLUGIN.HMR`                   | 对应 `HotModuleReplacementPlugin`                                                  |
+| `PLUGIN.COPY`                  | 对应 `CopyWebpackPlugin`                                                           |
+| `PLUGIN.HTML`                  | 对应 `HtmlWebpackPlugin`，使用时需要拼接 entry 名称：`${PLUGIN.HTML}-${entryName}` |
+| `PLUGIN.DEFINE`                | 对应 `DefinePlugin`                                                                |
+| `PLUGIN.IGNORE`                | 对应 `IgnorePlugin`                                                                |
+| `PLUGIN.BANNER`                | 对应 `BannerPlugin`                                                                |
+| `PLUGIN.PROGRESS`              | 对应 `Webpackbar`                                                                  |
+| `PLUGIN.APP_ICON`              | 对应 `AppIconPlugin`                                                               |
+| `PLUGIN.MANIFEST`              | 对应 `WebpackManifestPlugin`                                                       |
+| `PLUGIN.TS_CHECKER`            | 对应 `ForkTsCheckerWebpackPlugin`                                                  |
+| `PLUGIN.INLINE_HTML`           | 对应 `InlineChunkHtmlPlugin`                                                       |
+| `PLUGIN.BUNDLE_ANALYZER`       | 对应 `WebpackBundleAnalyzer`                                                       |
+| `PLUGIN.MINI_CSS_EXTRACT`      | 对应 `MiniCssExtractPlugin`                                                        |
+| `PLUGIN.VUE_LOADER_PLUGIN`     | 对应 `VueLoaderPlugin`                                                             |
+| `PLUGIN.REACT_FAST_REFRESH`    | 对应 `ReactFastRefreshPlugin`                                                      |
+| `PLUGIN.NODE_POLYFILL_PROVIDE` | 对应处理 node polyfill 的 `ProvidePlugin`                                          |
+| `PLUGIN.SUBRESOURCE_INTEGRITY` | 对应 `webpack-subresource-integrity`                                               |
+| `PLUGIN.ASSETS_RETRY`          | 对应 webpack 静态资源重试插件 `WebpackAssetsRetryPlugin`              |
+| `PLUGIN.AUTO_SET_ROOT_SIZE`    | 对应自动设置根字体大小插件 `AutoSetRootSizePlugin`                    |
+
+#### CHAIN_ID.MINIMIZER
+
+通过 `MINIMIZER.XXX` 可以匹配到对应的压缩工具。
+
+| ID                  | 描述                             |
+| ------------------- | -------------------------------- |
+| `MINIMIZER.JS`      | 对应 `TerserWebpackPlugin`       |
+| `MINIMIZER.CSS`     | 对应 `CssMinimizerWebpackPlugin` |
+| `MINIMIZER.ESBUILD` | 对应 `ESBuildPlugin`             |
+| `MINIMIZER.SWC`     | 对应 `SwcWebpackPlugin`          |
+
+### 使用示例
+
+使用示例可参考：[WebpackChain 使用示例](https://modernjs.dev/builder/guide/advanced/custom-webpack-config.html#%E4%BD%BF%E7%94%A8-webpack-chain)。

package/docs/zh/configure/app/tools/webpack.mdx

@@ -4,6 +4,299 @@ title: webpack
 
 # tools.webpack
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpack.md';
+- **类型：** `Object | Function | undefined`
+- **默认值：** `undefined`
+- **打包工具：** `仅支持 webpack`
 
-<Main />
+`tools.webpack` 选项用于配置原生的 [webpack](https://webpack.js.org/)。
+
+> `tools.bundlerChain` 同样可以修改 webpack 配置，并且功能更加强大，建议优先使用 `tools.bundlerChain`。
+
+### Object 类型
+
+`tools.webpack` 可以配置为一个对象，这个对象将会和内置的 webpack 配置通过 [webpack-merge](https://github.com/survivejs/webpack-merge) 进行深层合并。
+
+比如添加 `resolve.alias` 配置：
+
+```js
+export default {
+  tools: {
+    webpack: {
+      resolve: {
+        alias: {
+          '@util': 'src/util',
+        },
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+`tools.webpack` 也可以配置为一个函数，这个函数的第一个入参为内置的 webpack 配置对象，你可以对这个对象进行修改，然后返回一份新的配置。比如：
+
+```js
+export default {
+  tools: {
+    webpack: config => {
+      config.resolve.alias['@util'] = 'src/util';
+      return config;
+    },
+  },
+};
+```
+
+:::tip
+`tools.webpack` 函数返回的对象会直接作为最终使用的 webpack 配置，不会再与内置的 webpack 配置进行合并。
+:::
+
+### 工具集合
+
+这个函数的第二个参数是一个对象，包含了一些工具函数和属性，详情如下：
+
+#### env
+
+- **类型：** `'development' | 'production' | 'test'`
+
+通过 env 参数可以判断当前环境为 development、production 还是 test。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { env }) => {
+      if (env === 'development') {
+        config.devtool = 'cheap-module-eval-source-map';
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isProd
+
+- **类型：** `boolean`
+
+通过 isProd 参数可以判断当前环境是否为 production。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isProd }) => {
+      if (isProd) {
+        config.devtool = 'source-map';
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### target
+
+- **类型：** `'web' | 'node' | 'modern-web' | 'web-worker'`
+
+通过 target 参数可以判断当前构建的目标运行时环境。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { target }) => {
+      if (target === 'node') {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isServer
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `node`，等价于 `target === 'node'`。
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isServer }) => {
+      if (isServer) {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### isWebWorker
+
+- **类型：** `boolean`
+
+判断当前构建的目标运行时环境是否为 `web-worker`，等价于 `target === 'web-worker'`。
+
+```js
+export default {
+  tools: {
+    webpack: (config, { isWebWorker }) => {
+      if (isWebWorker) {
+        // ...
+      }
+      return config;
+    },
+  },
+};
+```
+
+#### webpack
+
+- **类型：** `typeof import('webpack')`
+
+通过这个参数你可以拿到 webpack 实例。比如：
+
+```js
+export default {
+  tools: {
+    webpack: (config, { webpack }) => {
+      config.plugins.push(new webpack.ProgressPlugin());
+      return config;
+    },
+  },
+};
+```
+
+#### HtmlWebpackPlugin
+
+- **类型：** `typeof import('html-webpack-plugin')`
+
+通过这个参数你可以拿到 HtmlWebpackPlugin 实例。
+
+```js
+export default {
+  tools: {
+    webpack: (chain, { HtmlWebpackPlugin }) => {
+      console.log(HtmlWebpackPlugin);
+    },
+  },
+};
+```
+
+#### addRules
+
+- **类型：** `(rules: RuleSetRule | RuleSetRule[]) => void`
+
+添加额外的 [webpack rules](https://webpack.js.org/configuration/module/#modulerules)。
+
+示例：
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { addRules }) => {
+      // 添加单条规则
+      addRules({
+        test: /\.foo/,
+        loader: require.resolve('foo-loader'),
+      });
+
+      // 以数组形式添加多条规则
+      addRules([
+        {
+          test: /\.foo/,
+          loader: require.resolve('foo-loader'),
+        },
+        {
+          test: /\.bar/,
+          loader: require.resolve('bar-loader'),
+        },
+      ]);
+    },
+  },
+};
+```
+
+#### prependPlugins
+
+- **类型：** `(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void`
+
+在内部 webpack 插件数组头部添加额外的插件，数组头部的插件会优先执行。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { prependPlugins, webpack }) => {
+      // 添加单个插件
+      prependPlugins(
+        new webpack.BannerPlugin({
+          banner: 'hello world!',
+        }),
+      );
+
+      // 以数组形式添加多个插件
+      prependPlugins([new PluginA(), new PluginB()]);
+    },
+  },
+};
+```
+
+#### appendPlugins
+
+- **类型：** `(plugins: WebpackPluginInstance | WebpackPluginInstance[]) => void`
+
+在内部 webpack 插件数组尾部添加额外的插件，数组尾部的插件会在最后执行。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { appendPlugins, webpack }) => {
+      // 添加单个插件
+      appendPlugins([
+        new webpack.BannerPlugin({
+          banner: 'hello world!',
+        }),
+      ]);
+
+      // 以数组形式添加多个插件
+      appendPlugins([new PluginA(), new PluginB()]);
+    },
+  },
+};
+```
+
+#### removePlugin
+
+- **类型：** `(name: string) => void`
+
+删除内部的 webpack 插件，参数为该插件的 `constructor.name`。
+
+例如，删除内部的 [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin)：
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { removePlugin }) => {
+      removePlugin('ForkTsCheckerWebpackPlugin');
+    },
+  },
+};
+```
+
+#### mergeConfig
+
+- **类型：** `(...configs: WebpackConfig[]) => WebpackConfig`
+
+用于合并多份 webpack 配置，等价于 [webpack-merge](https://github.com/survivejs/webpack-merge)。
+
+```ts
+export default {
+  tools: {
+    webpack: (config, { mergeConfig }) => {
+      return mergeConfig(config, {
+        devtool: 'eval',
+      });
+    },
+  },
+};
+```

package/docs/zh/guides/_meta.json

@@ -24,11 +24,6 @@
     "name": "topic-detail",
     "label": "topic"
   },
-  {
-    "type": "dir",
-    "name": "rsbuild-plugins",
-    "label": "构建插件"
-  },
   {
     "type": "dir",
     "name": "troubleshooting",

package/docs/zh/guides/advanced-features/_meta.json

@@ -6,13 +6,15 @@
     "label": "use-bff",
     "collapsed": true
   },
-  "code-split",
+  {
+    "type": "dir",
+    "name": "page-performance",
+    "label": "page-performance",
+    "collapsed": true
+  },
+  "build-performance",
   "compatibility",
-  "eslint",
   "low-level",
   "source-build",
-  "build-performance",
-  "inline-assets",
-  "optimize-bundle",
   "web-server"
 ]

package/docs/zh/guides/advanced-features/bff/_meta.json

@@ -1 +1 @@
-["function", "type", "frameworks", "sdk"]
+["function", "frameworks", "extend-server", "sdk"]