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

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

@@ -4,6 +4,222 @@ title: babel
 
 # tools.babel
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/babel.md';
+- **类型：** `Object | Function`
+- **默认值：** `undefined`
+
+通过 `tools.babel` 可以修改 [babel-loader](https://github.com/babel/babel-loader) 的配置项。
+
+### 使用场景
+
+请留意 `tools.babel` 在以下使用场景中的局限性：
+
+- Rspack 场景：在使用 Rspack 作为打包工具时，使用 `tools.babel` 配置项将会明显拖慢 Rspack 构建速度。因为 Rspack 默认使用的是 SWC 编译，配置 Babel 会导致代码需要被编译两次，产生了额外的编译开销。
+- webpack + SWC 场景：在使用 webpack 作为打包工具时，如果你使用了 SWC 插件进行代码编译，那么 `tools.babel` 选项将不会生效。
+
+### Function 类型
+
+当 `tools.babel` 为 Function 类型时，默认 Babel 配置会作为第一个参数传入，你可以直接修改配置对象，也可以返回一个对象作为最终的 `babel-loader` 配置。
+
+```js
+export default {
+  tools: {
+    babel(config) {
+      // 添加一个插件，比如配置某个组件库的按需引入
+      config.plugins.push([
+        'babel-plugin-import',
+        {
+          libraryName: 'xxx-components',
+          libraryDirectory: 'es',
+          style: true,
+        },
+      ]);
+    },
+  },
+};
+```
+
+`tools.babel` 函数的第二个参数提供了一些方便的工具函数，请继续阅读下方文档。
+
+:::tip
+以上示例仅作为参考，通常来说，你不需要手动配置 `babel-plugin-import`，因为 Modern.js 已经提供了更通用的 `source.transformImport` 配置。
+:::
+
+### Object 类型
+
+当 `tools.babel` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 浅合并。
+
+:::caution
+`Object.assign` 是浅拷贝，会完全覆盖内置的 `presets` 或 `plugins` 数组，导致内置的 presets 或 plugins 失效，请在明确影响面的情况下再使用这种方式。
+:::
+
+```js
+export default {
+  tools: {
+    babel: {
+      plugins: [
+        [
+          'babel-plugin-import',
+          {
+            libraryName: 'xxx-components',
+            libraryDirectory: 'es',
+            style: true,
+          },
+        ],
+      ],
+    },
+  },
+};
+```
+
+### 工具函数
+
+`tools.babel` 为 Function 类型时，第二个参数可用的工具函数如下:
+
+#### addPlugins
+
+- **类型：** `(plugins: BabelPlugin[]) => void`
+
+添加若干个 Babel 插件。
+
+```js
+export default {
+  tools: {
+    babel(config, { addPlugins }) {
+      addPlugins([
+        [
+          'babel-plugin-import',
+          {
+            libraryName: 'xxx-components',
+            libraryDirectory: 'es',
+            style: true,
+          },
+        ],
+      ]);
+    },
+  },
+};
+```
+
+#### addPresets
+
+- **类型：** `(presets: BabelPlugin[]) => void`
+
+添加若干个 Babel 预设配置 (大多数情况下不需要增加预设)。
+
+```js
+export default {
+  tools: {
+    babel(config, { addPresets }) {
+      addPresets(['@babel/preset-env']);
+    },
+  },
+};
+```
+
+#### removePlugins
+
+- **类型：** `(plugins: string | string[]) => void`
+
+移除 Babel 插件，传入需要移除的插件名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
+
+```js
+export default {
+  tools: {
+    babel(config, { removePlugins }) {
+      removePlugins('babel-plugin-import');
+    },
+  },
+};
+```
+
+#### removePresets
+
+- **类型：** `(presets: string | string[]) => void`
+
+移除 Babel 预设配置，传入需要移除的预设名称即可，你可以传入单个字符串，也可以传入一个字符串数组。
+
+```js
+export default {
+  tools: {
+    babel(config, { removePresets }) {
+      removePresets('@babel/preset-env');
+    },
+  },
+};
+```
+
+#### modifyPresetEnvOptions
+
+- **类型：** `(options: PresetEnvOptions) => void`
+
+修改 [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+
+```js
+export default {
+  tools: {
+    babel(config, { modifyPresetEnvOptions }) {
+      modifyPresetEnvOptions({
+        targets: "last 2 versions",
+      });
+    },
+  },
+};
+```
+
+```js
+export default {
+  tools: {
+    babel(config, { modifyPresetEnvOptions }) {
+      modifyPresetEnvOptions({
+        targets: {
+          chrome: "58",
+          ie: "11"
+        }
+      });
+    },
+  },
+};
+```
+
+#### modifyPresetReactOptions
+
+- **类型：** `(options: PresetReactOptions) => void`
+
+修改 [@babel/preset-react](https://babeljs.io/docs/en/babel-preset-react) 的配置项，传入的配置会与默认配置进行浅层合并，比如:
+
+```js
+export default {
+  tools: {
+    babel(config, { modifyPresetReactOptions }) {
+      modifyPresetReactOptions({
+        pragma: 'React.createElement',
+      });
+    },
+  },
+};
+```
+
+#### addIncludes
+
+已废弃，请使用 [source.include](https://modernjs.dev/configure/app/source/include.html) 代替，两者功能完全一致。
+
+#### addExcludes
+
+已废弃，请使用 [source.exclude](https://modernjs.dev/configure/app/source/exclude.html) 代替，两者功能完全一致。
+
+### 调试 Babel 配置
+
+当你通过 `tools.babel` 修改 `babel-loader` 配置后，可以在 [调试模式](https://rsbuild.dev/zh/guide/debug/debug-mode) 下查看最终生成的配置。
+
+首先通过 `DEBUG=builder` 参数开启调试模式：
+
+```bash
+# 调试开发环境
+DEBUG=builder pnpm dev
+
+# 调试生产环境
+DEBUG=builder pnpm build
+```
+
+然后打开生成的 `(webpack|rspack).config.web.js`，搜索 `babel-loader` 关键词，即可看到完整的 `babel-loader` 配置内容。
 
-<Main />

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

@@ -4,6 +4,30 @@ title: bundlerChain
 
 # tools.bundlerChain
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/bundlerChain.mdx';
+- **类型：**
 
-<Main />
+```ts
+type BundlerChainFn = (
+  chain: RspackChain | webpackChain,
+  utils: ModifyBundlerChainUtils,
+) => Promise<void> | void;
+```
+
+- **默认值：** `undefined`
+
+你可以通过 `tools.bundlerChain` 来修改默认的 webpack 和 Rspack 配置，它的值为 `Function` 类型，接收两个参数：
+
+- 第一个参数为 `bundler-chain` 对象实例，你可以通过这个实例来修改 webpack 和 Rspack 的配置。
+- 第二个参数为一个工具集合，包括`env`、`isProd`、`CHAIN_ID` 等。
+
+:::tip 什么是 BundlerChain
+
+Bundler chain 是 webpack chain 的子集，其中包含一部分 webpack chain API，你可以用它来同时修改 webpack 和 Rspack 的配置。
+
+通过 bundler chain 修改的配置，在 webpack 和 Rspack 构建时均可生效。需要注意的是，bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如，修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同)，或添加一个[Rspack 兼容](https://rspack.dev/zh/guide/compatibility/plugin)的 webpack 插件。
+
+:::
+
+> `tools.bundlerChain` 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack，因此会被其他几个配置中的修改所覆盖。
+
+更多信息可参考 [Rsbuild#tools.bundlerChain](https://rsbuild.dev/zh/config/tools/bundler-chain)。

package/docs/zh/configure/app/tools/css-extract.mdx

@@ -1,9 +1,35 @@
 ---
 title: cssExtract
+configName: tools.cssExtract
 ---
 
 # tools.cssExtract
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/cssExtract.md';
+- **类型：**
 
-<Main />
+```ts
+type CSSExtractOptions = {
+  pluginOptions?: Rspack.CssExtractRspackPluginOptions;
+  loaderOptions?: Rspack.CssExtractRspackLoaderOptions;
+};
+```
+
+- **默认值：**
+
+```js
+const defaultOptions = {
+  pluginOptions: {
+    ignoreOrder: true,
+    // 默认值由 Rsbuild 的 output.distPath 和 output.filename 选项决定
+    filename: 'static/css/[name].css',
+    chunkFilename: 'static/css/async/[name].css',
+  },
+  loaderOptions: {},
+};
+```
+
+通过 `tools.cssExtract` 可以更改 [CssExtractRspackPlugin](https://www.rspack.dev/zh/plugins/rspack/css-extract-rspack-plugin) 或 [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) 的配置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/tools/css-loader.mdx

@@ -1,9 +1,22 @@
 ---
 title: cssLoader
+configName: tools.cssLoader
 ---
 
 # tools.cssLoader
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/cssLoader.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  modules: rsbuildConfig.output.cssModules,
+  sourceMap: rsbuildConfig.output.sourceMap.css,
+};
+```
+
+修改 [css-loader](https://github.com/webpack-contrib/css-loader) 的配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />