@modern-js/main-doc 2.60.0 → 2.60.1

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

@@ -4,6 +4,222 @@ title: babel
 
 # tools.babel
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/babel.md';
+- **Type:** `Object | Function`
+- **Default:** `undefined`
 
-<Main />
+With `tools.babel` you can modify the options of [babel-loader](https://github.com/babel/babel-loader).
+
+### Usage Scenarios
+
+Please note the limitations of `tools.babel` in the following usage scenarios:
+
+- Rspack scenario: When using Rspack as the bundler, using the `tools.babel` option will significantly slow down the Rspack's build speed. This is because Rspack defaults to using SWC for compilation, and configuring Babel will cause the code to be compiled twice, resulting in additional compilation overhead.
+- webpack + SWC scenario: When using webpack as the bundler, if you use SWC plugin for code compilation, the `tools.babel` option will not take effect.
+
+### Function Type
+
+When `tools.babel` is of type `Function`, the default Babel configuration will be passed as the first parameter. You can directly modify the configuration object or return an object as the final `babel-loader` configuration.
+
+```js
+export default {
+  tools: {
+    babel(config) {
+      // Add a Babel plugin
+      // note: the plugin have been added to the default config to support antd load on demand
+      config.plugins.push([
+        'babel-plugin-import',
+        {
+          libraryName: 'xxx-components',
+          libraryDirectory: 'es',
+          style: true,
+        },
+      ]);
+    },
+  },
+};
+```
+
+The second parameter of the `tools.babel` function provides some more convenient utility functions. Please continue reading the documentation below.
+
+:::tip
+The above example is just for reference, usually you don't need to manually configure `babel-plugin-import`, because Modern.js already provides a more general `source.transformImport` configuration.
+:::
+
+### Object Type
+
+When `tools.babel`'s type is `Object`, the config will be shallow merged with default config by `Object.assign`.
+
+:::caution
+Note that `Object.assign` is a shallow copy and will completely overwrite the built-in `presets` or `plugins` array, please use it with caution.
+:::
+
+```js
+export default {
+  tools: {
+    babel: {
+      plugins: [
+        [
+          'babel-plugin-import',
+          {
+            libraryName: 'xxx-components',
+            libraryDirectory: 'es',
+            style: true,
+          },
+        ],
+      ],
+    },
+  },
+};
+```
+
+### Util Functions
+
+When `tools.babel` is a Function, the tool functions available for the second parameter are as follows:
+
+#### addPlugins
+
+- **Type:** `(plugins: BabelPlugin[]) => void`
+
+Add some Babel plugins. For example:
+
+```js
+export default {
+  tools: {
+    babel(config, { addPlugins }) {
+      addPlugins([
+        [
+          'babel-plugin-import',
+          {
+            libraryName: 'xxx-components',
+            libraryDirectory: 'es',
+            style: true,
+          },
+        ],
+      ]);
+    },
+  },
+};
+```
+
+#### addPresets
+
+- **Type:** `(presets: BabelPlugin[]) => void`
+
+Add Babel preset configuration. (No need to add presets in most cases)
+
+```js
+export default {
+  tools: {
+    babel(config, { addPresets }) {
+      addPresets(['@babel/preset-env']);
+    },
+  },
+};
+```
+
+#### removePlugins
+
+- **Type:** `(plugins: string | string[]) => void`
+
+To remove the Babel plugin, just pass in the name of the plugin to be removed, you can pass in a single string or an array of strings.
+
+```js
+export default {
+  tools: {
+    babel(config, { removePlugins }) {
+      removePlugins('babel-plugin-import');
+    },
+  },
+};
+```
+
+#### removePresets
+
+- **Type:** `(presets: string | string[]) => void`
+
+To remove the Babel preset configuration, pass in the name of the preset to be removed, you can pass in a single string or an array of strings.
+
+```js
+export default {
+  tools: {
+    babel(config, { removePresets }) {
+      removePresets('@babel/preset-env');
+    },
+  },
+};
+```
+
+#### modifyPresetEnvOptions
+
+- **Type:** `(options: PresetEnvOptions) => void`
+
+Modify the configuration of [@babel/preset-env](https://babeljs.io/docs/en/babel-preset-env), the configuration you pass in will be shallowly merged with default config. For example:
+
+```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
+
+- **Type:** `(options: PresetReactOptions) => void`
+
+Modify the configuration of [@babel/preset-react](https://babeljs.io/docs/en/babel-preset-react), the configuration you pass in will be shallowly merged with default config. For example:
+
+```js
+export default {
+  tools: {
+    babel(config, { modifyPresetReactOptions }) {
+      modifyPresetReactOptions({
+        pragma: 'React.createElement',
+      });
+    },
+  },
+};
+```
+
+#### addIncludes
+
+Deprecated, please use [source.include](https://modernjs.dev/en/configure/app/source/include.html) instead, both have the same functionality.
+
+#### addExcludes
+
+Deprecated, please use [source.exclude](https://modernjs.dev/en/configure/app/source/exclude.html) instead, both have the same functionality.
+
+### Debugging Babel Configuration
+
+After modifying the `babel-loader` configuration through `tools.babel`, you can view the final generated configuration in [Rsbuild debug mode](https://rsbuild.dev/guide/debug/debug-mode).
+
+First, enable debug mode by using the `DEBUG=builder` parameter:
+
+```bash
+# Debug development mode
+DEBUG=builder pnpm dev
+
+# Debug production mode
+DEBUG=builder pnpm build
+```
+
+Then open the generated `(webpack|rspack).config.web.js` file and search for the `babel-loader` keyword to see the complete `babel-loader` configuration.

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

@@ -4,6 +4,27 @@ title: bundlerChain
 
 # tools.bundlerChain
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/bundlerChain.mdx';
+- **Type:**
 
-<Main />
+```ts
+type BundlerChainFn = (
+  chain: RspackChain | webpackChain,
+  utils: ModifyBundlerChainUtils,
+) => Promise<void> | void;
+```
+
+- **Default:** `undefined`
+
+You can modify the webpack and Rspack configuration by configuring `tools.bundlerChain` which is type of `Function`. The function receives two parameters, the first is the original bundler chain object, and the second is an object containing some utils.
+
+:::tip What is BundlerChain
+
+Bundler chain is a subset of webpack chain, which contains part of the webpack chain API that you can use to modify both webpack and Rspack configuration.
+
+Configurations modified via bundler chain will work on both webpack and Rspack builds. Note that the bundler chain only supports modifying the configuration of the non-differentiated parts of webpack and Rspack. For example, modifying the devtool configuration option (webpack and Rspack have the same devtool property value type), or adding an [Rspack-compatible](https://rspack.dev/guide/compatibility/plugin) webpack plugin.
+
+:::
+
+> `tools.bundlerChain` is executed earlier than tools.webpackChain / tools.webpack / tools.rspack and thus will be overridden by changes in others.
+
+For more information, please refer to [Rsbuild#tools.bundlerChain](https://rsbuild.dev/config/tools/bundler-chain).

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

@@ -1,9 +1,38 @@
 ---
 title: cssExtract
+configName: tools.cssExtract
 ---
 
 # tools.cssExtract
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/cssExtract.md';
+- **Type:**
 
-<Main />
+```ts
+type CSSExtractOptions = {
+  pluginOptions?: Rspack.CssExtractRspackPluginOptions;
+  loaderOptions?: Rspack.CssExtractRspackLoaderOptions;
+};
+```
+
+- **Default:**
+
+```js
+const defaultOptions = {
+  // The loader options
+  loaderOptions: {},
+  // The plugin options
+  pluginOptions: {
+    // The default value of cssPath is `static/css`
+    // while the default value of cssFilename is `[name].[contenthash:8].css`
+    filename: `${cssPath}/${cssFilename}`,
+    chunkFilename: `${cssPath}/async/${cssFilename}`,
+    ignoreOrder: true,
+  },
+};
+```
+
+The config of [CssExtractRspackPlugin](https://www.rspack.dev/plugins/rspack/css-extract-rspack-plugin) / [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) can be modified through `tools.cssExtract`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,18 @@ title: cssLoader
 
 # tools.cssLoader
 
-import Main from '@modern-js/builder-doc/docs/en/config/tools/cssLoader.md';
+- **Type:** `Object | Function`
+- **Default:**
 
-<Main />
+```js
+const defaultOptions = {
+  modules: rsbuildConfig.output.cssModules,
+  sourceMap: rsbuildConfig.output.sourceMap.css,
+};
+```
+
+The config of [css-loader](https://github.com/webpack-contrib/css-loader) can be modified through `tools.cssLoader`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />