@modern-js/main-doc 3.9.2 → 3.9.3

package/docs/en/configure/app/output/disable-svgr.mdx

@@ -7,6 +7,10 @@ title: disableSvgr
 - **Type:** `boolean`
 - **Default:** `false`
 
+:::warning Deprecated
+`output.disableSvgr` is deprecated and will be removed in the next major version. Replace `output.disableSvgr: true` with [tools.svgr](/configure/app/tools/svgr) set to `false`; `output.disableSvgr: false` is the default behavior and can simply be removed. When both are set, `tools.svgr` wins.
+:::
+
 Whether to transform SVGs into React components. If true, will treat all .svg files as assets.
 
 By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting `disableSvgr` to true to improve build performance.

package/docs/en/configure/app/output/svg-default-export.mdx

@@ -7,6 +7,10 @@ title: svgDefaultExport
 - **Type:** `'url' | 'component'`
 - **Default:** `'url'`
 
+:::warning Deprecated
+`output.svgDefaultExport` is deprecated and will be removed in the next major version. Use `svgrOptions.exportType` of [tools.svgr](/configure/app/tools/svgr) instead: `'component'` maps to `exportType: 'default'`, `'url'` maps to `exportType: 'named'`. When both are set, `tools.svgr` wins.
+:::
+
 `output.svgDefaultExport` is used to configure the default export type of SVG files.
 
 When `output.svgDefaultExport` is set to `url` , the default export of SVG files is the URL of the file. For example:

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

@@ -9,49 +9,78 @@ title: less
 
 ```js
 const defaultOptions = {
-  lessOptions: {
-    javascriptEnabled: true,
+  lessLoaderOptions: {
+    lessOptions: {
+      javascriptEnabled: true,
+    },
+    // CSS Source Map enabled by default in development environment
+    sourceMap: isDev,
   },
-  // CSS Source Map enabled by default in development environment
-  sourceMap: isDev,
 };
 ```
 
-You can modify the config of [less-loader](https://github.com/webpack-contrib/less-loader) via `tools.less`.
+`tools.less` modifies the options of [@rsbuild/plugin-less](https://rsbuild.rs/plugins/list/plugin-less). It accepts the full plugin options:
+
+| Option              | Description                                                                                    |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `lessLoaderOptions` | Options passed to [less-loader](https://github.com/webpack-contrib/less-loader), object or function |
+| `include`           | Files handled by less-loader, defaults to `/\.less$/`                                          |
+| `exclude`           | Files that less-loader should skip                                                             |
+| `parallel`          | Whether to compile Less modules in worker threads, defaults to `false`                         |
+
+### Modifying less-loader options
+
+When `lessLoaderOptions` is an `Object`, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
 
-### Object Type
+```js
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: {
+          javascriptEnabled: false,
+        },
+      },
+    },
+  },
+};
+```
 
-When `tools.less` is configured as `Object` type, it is merged with the default config through Object.assign in a shallow way. It should be noted that `lessOptions` is merged through deepMerge in a deep way. For example:
+When `lessLoaderOptions` is a `Function`, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
 
 ```js
 export default {
   tools: {
     less: {
-      lessOptions: {
-        javascriptEnabled: false,
+      lessLoaderOptions(config) {
+        // Modify the config of lessOptions
+        config.lessOptions = {
+          javascriptEnabled: false,
+        };
       },
     },
   },
 };
 ```
 
-### Function Type
+### Parallel compilation
 
-When `tools.less` is a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
+Less compilation is pure JavaScript and runs on the Node.js main thread by default. With `parallel` enabled, Less modules are compiled in a pool of worker threads, which shortens the build when a project has many Less files.
 
 ```js
 export default {
   tools: {
-    less(config) {
-      // Modify the config of lessOptions
-      config.lessOptions = {
-        javascriptEnabled: false,
-      };
+    less: {
+      parallel: true,
     },
   },
 };
 ```
 
+:::tip
+Options sent to worker threads must satisfy the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). With `parallel` enabled, `lessLoaderOptions` therefore cannot contain functions, such as an `additionalData` function or a custom `implementation`.
+:::
+
 ### Modifying Less Version
 
 In some scenarios, if you need to use a specific version of Less instead of the built-in Less v4 in Modern.js, you can install the desired Less version in your project and set it up using the `implementation` option of the `less-loader`.
@@ -60,7 +89,9 @@ In some scenarios, if you need to use a specific version of Less instead of the
 export default {
   tools: {
     less: {
-      implementation: require('less'),
+      lessLoaderOptions: {
+        implementation: require('less'),
+      },
     },
   },
 };
@@ -77,8 +108,53 @@ Used to specify which files `less-loader` does not compile, You can pass in one
 ```js
 export default {
   tools: {
-    less(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    less: {
+      lessLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+The plugin's `exclude` option is the recommended equivalent:
+
+```js
+export default {
+  tools: {
+    less: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### Legacy form
+
+:::warning Do not mix the two layers
+As soon as an object contains a plugin-level key (`lessLoaderOptions`, `include`, `exclude`, ...), the whole object is parsed as plugin options and any loader option in it has no effect. For example, `lessOptions` in `tools.less: { parallel: true, lessOptions: { ... } }` is ignored and must be moved under `lessLoaderOptions`; a hint is printed in development.
+:::
+
+
+In earlier versions, `tools.less` took the less-loader options directly, e.g. `tools.less: { lessOptions: {} }` or `tools.less(config, { addExcludes }) {}`. This form still works: Modern.js wraps it into `lessLoaderOptions` and produces exactly the same config as before. A migration hint is printed in development, and the legacy form will be removed in the next major version.
+
+```js
+// legacy
+export default {
+  tools: {
+    less: {
+      lessOptions: { javascriptEnabled: false },
+    },
+  },
+};
+
+// current
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: { javascriptEnabled: false },
+      },
     },
   },
 };

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

@@ -9,41 +9,64 @@ title: sass
 
 ```js
 const defaultOptions = {
-  // CSS Source Map enabled by default in development environment
-  sourceMap: isDev,
+  sassLoaderOptions: {
+    // CSS Source Map enabled by default in development environment
+    sourceMap: isDev,
+  },
 };
 ```
 
-You can modify the config of [sass-loader](https://github.com/webpack-contrib/sass-loader) via `tools.sass`.
+`tools.sass` modifies the options of [@rsbuild/plugin-sass](https://rsbuild.rs/plugins/list/plugin-sass). It accepts the full plugin options:
 
-### Object Type
+| Option              | Description                                                                                    |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `sassLoaderOptions` | Options passed to [sass-loader](https://github.com/webpack-contrib/sass-loader), object or function |
+| `include`           | Files handled by sass-loader, defaults to `/\.s(?:a|c)ss$/`                                    |
+| `exclude`           | Files that sass-loader should skip                                                             |
+| `rewriteUrls`       | Whether to rewrite relative URLs in Sass files with resolve-url-loader, defaults to `true`     |
 
-When `tools.sass` is `Object` type, it is merged with the default config through Object.assign. It should be noted that `sassOptions` is merged through deepMerge in a deep way.
+### Modifying sass-loader options
 
-For example:
+When `sassLoaderOptions` is an `Object`, it is merged with the default config through Object.assign in a shallow way. It should be noted that `sassOptions` is merged through deepMerge in a deep way. For example:
 
 ```js
 export default {
   tools: {
     sass: {
-      sourceMap: true,
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
+    },
+  },
+};
+```
+
+When `sassLoaderOptions` is a `Function`, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For example:
+
+```js
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions(config) {
+        // Modify the additionalData config
+        config.additionalData = async (content, loaderContext) => {
+          // ...
+        };
+      },
     },
   },
 };
 ```
 
-### Function Type
+### Disabling URL rewriting
 
-When `tools.sass` is a Function, the default config is passed as the first parameter, which can be directly modified or returned as the final result. The second parameter provides some utility functions that can be called directly. For Example:
+By default, relative URLs in Sass files are rewritten by resolve-url-loader so that they resolve relative to the source file. If your project does not rely on this, turn it off to drop one loader from the chain:
 
 ```js
 export default {
   tools: {
-    sass(config) {
-      // Modify sourceMap config
-      config.additionalData = async (content, loaderContext) => {
-        // ...
-      };
+    sass: {
+      rewriteUrls: false,
     },
   },
 };
@@ -57,13 +80,15 @@ In some scenarios, if you need to use a specific version of Sass instead of the
 export default {
   tools: {
     sass: {
-      implementation: require('sass'),
+      sassLoaderOptions: {
+        implementation: require('sass'),
+      },
     },
   },
 };
 ```
 
-### Utility Function
+### Util Function
 
 #### addExcludes
 
@@ -74,8 +99,53 @@ Used to specify which files `sass-loader` does not compile, You can pass in one
 ```js
 export default {
   tools: {
-    sass(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    sass: {
+      sassLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+The plugin's `exclude` option is the recommended equivalent:
+
+```js
+export default {
+  tools: {
+    sass: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### Legacy form
+
+:::warning Do not mix the two layers
+As soon as an object contains a plugin-level key (`sassLoaderOptions`, `include`, `exclude`, ...), the whole object is parsed as plugin options and any loader option in it has no effect. For example, `sassOptions` in `tools.sass: { rewriteUrls: false, sassOptions: { ... } }` is ignored and must be moved under `sassLoaderOptions`; a hint is printed in development.
+:::
+
+
+In earlier versions, `tools.sass` took the sass-loader options directly, e.g. `tools.sass: { sassOptions: {} }` or `tools.sass(config, { addExcludes }) {}`. This form still works: Modern.js wraps it into `sassLoaderOptions` and produces exactly the same config as before. A migration hint is printed in development, and the legacy form will be removed in the next major version.
+
+```js
+// legacy
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+
+// current
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
     },
   },
 };

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

@@ -0,0 +1,93 @@
+---
+title: svgr
+---
+
+# tools.svgr
+
+- **Type:** `Object | Function | false`
+- **Default:**
+
+```js
+const defaultOptions = {
+  mixedImport: true,
+  svgrOptions: {
+    exportType: 'named',
+  },
+};
+```
+
+`tools.svgr` modifies the options of [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr). It accepts the full plugin options. Set it to `false` to skip registering the SVGR plugin; all `.svg` files are then treated as static assets.
+
+| Option            | Description                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `svgrOptions`     | Options passed to [SVGR](https://react-svgr.com/docs/options/), such as `exportType`, `icon`, `svgoConfig` |
+| `parallel`        | Whether to transform SVG files in worker threads, defaults to `false`                                |
+| `exclude`         | SVG files that SVGR should skip                                                                      |
+| `excludeImporter` | Importer files whose SVG imports should skip SVGR                                                    |
+| `query`           | Query that triggers the SVGR transform, defaults to `/react/`                                        |
+| `mixedImport`     | Whether a module may import both the URL and the React component, defaults to `true`                |
+
+### Merge rules
+
+When `tools.svgr` is an `Object`, its top-level fields are merged with the defaults through Object.assign in a shallow way, and `svgrOptions` is merged one level deeper, so setting only `svgrOptions.icon` keeps the default `exportType`.
+
+When `tools.svgr` is a `Function`, the default config is passed as the first parameter, which can be directly modified or returned as the final result. An array of objects and functions is also accepted and applied in order.
+
+### Parallel transform
+
+The SVGR transform is pure JavaScript and runs on the Node.js main thread by default. With many SVG files, enable `parallel` to move the transform into a pool of worker threads:
+
+```js
+export default {
+  tools: {
+    svgr: {
+      parallel: true,
+    },
+  },
+};
+```
+
+:::tip
+Options sent to worker threads must satisfy the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm). With `parallel` enabled, `svgrOptions` therefore cannot contain functions.
+:::
+
+### Changing the default export
+
+`svgrOptions.exportType` controls what an SVG file exports by default: `'named'` exports the file URL by default and the React component as the named export `ReactComponent`; `'default'` exports the React component by default.
+
+```js
+export default {
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
+  },
+};
+```
+
+### Disabling SVGR
+
+If you are sure that no SVG asset in your project is used as a React component, disable SVGR to improve build performance:
+
+```js
+export default {
+  tools: {
+    svgr: false,
+  },
+};
+```
+
+### Relation to the legacy options
+
+`tools.svgr` replaces the two deprecated options below. They still work today and will be removed in the next major version:
+
+| Legacy option                          | Replacement                                              |
+| -------------------------------------- | -------------------------------------------------------- |
+| `output.svgDefaultExport: 'component'` | `tools.svgr: { svgrOptions: { exportType: 'default' } }` |
+| `output.svgDefaultExport: 'url'`       | `tools.svgr: { svgrOptions: { exportType: 'named' } }`   |
+| `output.disableSvgr: true`             | `tools.svgr: false`                                      |
+| `output.disableSvgr: false`            | Default behavior, just remove it                         |
+
+When both are set, `tools.svgr` wins: once `tools.svgr` is set explicitly, `output.disableSvgr` no longer applies, and `tools.svgr.svgrOptions.exportType` overrides the value derived from `output.svgDefaultExport`.

package/docs/en/guides/basic-features/static-assets/svg-assets.mdx

@@ -42,16 +42,22 @@ export default () => <Logo />;
 
 ## Modify the Default Export
 
-You can modify the default export of SVG files through the [output.svgDefaultExport](/configure/app/output/svg-default-export) config. For example, set the default export as a React component:
+You can modify the default export of SVG files through `svgrOptions.exportType` of [tools.svgr](/configure/app/tools/svgr). For example, set the default export as a React component:
 
 ```ts
 export default {
-  output: {
-    svgDefaultExport: 'component',
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
   },
 };
 ```
 
+The legacy [output.svgDefaultExport](/configure/app/output/svg-default-export) config still works but is deprecated.
+
 Then import the SVG, you'll get a React component instead of a URL:
 
 ```tsx title="src/component/Logo.tsx"
@@ -78,12 +84,12 @@ Please read the [Import Static Assets](/guides/basic-features/static-assets) sec
 
 ## Disable SVGR Processing
 
-By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [disableSvgr](/configure/app/output/disable-svgr) to true to improve build performance.
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting [tools.svgr](/configure/app/tools/svgr) to `false` to improve build performance.
 
 ```js
 export default {
-  output: {
-    disableSvgr: true,
+  tools: {
+    svgr: false,
   },
 };
 ```
@@ -151,21 +157,27 @@ When SVGR is enabled, its default configuration is as follows:
 }
 ```
 
-If you need to modify the SVGR configuration, you can do the following:
+To modify the SVGR configuration, use `svgrOptions` of [tools.svgr](/configure/app/tools/svgr). The `svgoConfig.plugins` you pass are deep merged with the defaults by plugin name, so only the changed part needs to be written:
 
 ```js
 export default {
   tools: {
-    bundlerChain: (chain, { CHAIN_ID }) => {
-      chain.module
-        .rule(CHAIN_ID.RULE.SVG)
-        .oneOf(CHAIN_ID.ONE_OF.SVG)
-        .use(CHAIN_ID.USE.SVGR)
-        .tap(options => {
-          // modify svgoConfig
-          options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
-          return options;
-        });
+    svgr: {
+      svgrOptions: {
+        svgoConfig: {
+          plugins: [
+            {
+              name: 'preset-default',
+              params: {
+                overrides: {
+                  // add one more override on top of the default preset-default
+                  removeUselessDefs: false,
+                },
+              },
+            },
+          ],
+        },
+      },
     },
   },
 };

package/docs/en/plugin/introduction.mdx

@@ -129,7 +129,7 @@ The following are official Rsbuild plugins that are already built into Modern.js
 | Plugin                                                                                 | Description                                                                                                                                     | Modern.js Link                                                                                                                        |
 | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | [React Plugin](https://v2.rsbuild.rs/plugins/list/plugin-react)                        | Provides support for React                                                                                                                      | -                                                                                                                                     |
-| [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
+| [SVGR Plugin](https://v2.rsbuild.rs/plugins/list/plugin-svgr)                          | Supports converting SVG images into React components                                                                                            | [tools.svgr](/configure/app/tools/svgr)     |
 | [Assets Retry Plugin](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | Automatically retries requests when static asset loading fails                                                                                  | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
 | [Type Check Plugin](https://github.com/rstackjs/rsbuild-plugin-type-check)             | Runs TypeScript type checking in a separate process                                                                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
 | [Source Build Plugin](https://github.com/rstackjs/rsbuild-plugin-source-build)   | For monorepo scenarios, supports referencing source code from other subdirectories and completing builds and hot updates                        | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |

package/docs/zh/configure/app/output/disable-svgr.mdx

@@ -7,6 +7,10 @@ title: disableSvgr
 - **类型：** `boolean`
 - **默认值：** `false`
 
+:::warning 已废弃
+`output.disableSvgr` 已废弃，并将在下一个大版本中移除。`output.disableSvgr: true` 请改为 [tools.svgr](/configure/app/tools/svgr) 设置为 `false`；`output.disableSvgr: false` 是默认行为，直接删除即可。两者同时设置时，以 `tools.svgr` 为准。
+:::
+
 是否调用 SVGR 将 SVG 转化为 React 组件。如果设置为 true，将把所有的.svg 文件视为资源处理。
 
 默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。

package/docs/zh/configure/app/output/svg-default-export.mdx

@@ -7,6 +7,10 @@ title: svgDefaultExport
 - **类型：** `'url' | 'component'`
 - **默认值：** `'url'`
 
+:::warning 已废弃
+`output.svgDefaultExport` 已废弃，并将在下一个大版本中移除，请改用 [tools.svgr](/configure/app/tools/svgr) 的 `svgrOptions.exportType`：`'component'` 对应 `exportType: 'default'`，`'url'` 对应 `exportType: 'named'`。两者同时设置时，以 `tools.svgr` 为准。
+:::
+
 `output.svgDefaultExport` 可以用来配置 SVG 文件的默认导出。
 
 当 `output.svgDefaultExport` 配置为 `url` 时，SVG 文件的默认导出是文件的 URL。例如：

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

@@ -9,49 +9,78 @@ title: less
 
 ```js
 const defaultOptions = {
-  lessOptions: {
-    javascriptEnabled: true,
+  lessLoaderOptions: {
+    lessOptions: {
+      javascriptEnabled: true,
+    },
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
   },
-  // 默认在开发环境下启用 CSS 的 Source Map
-  sourceMap: isDev,
 };
 ```
 
-你可以通过 `tools.less` 修改 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置。
+`tools.less` 用于修改 [@rsbuild/plugin-less](https://rsbuild.rs/plugins/list/plugin-less) 的选项，取值为该插件的完整选项：
+
+| 选项                 | 说明                                                                               |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| `lessLoaderOptions`  | 传给 [less-loader](https://github.com/webpack-contrib/less-loader) 的选项，支持对象或函数 |
+| `include`            | 指定哪些文件交给 less-loader 处理，默认 `/\.less$/`                                  |
+| `exclude`            | 指定哪些文件不交给 less-loader 处理                                                  |
+| `parallel`           | 是否使用 worker 线程并行编译 Less，默认 `false`                                       |
+
+### 修改 less-loader 选项
 
-### Object 类型
+`lessLoaderOptions` 为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: {
+          javascriptEnabled: false,
+        },
+      },
+    },
+  },
+};
+```
 
-当 `tools.less` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+`lessLoaderOptions` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
 
 ```js
 export default {
   tools: {
     less: {
-      lessOptions: {
-        javascriptEnabled: false,
+      lessLoaderOptions(config) {
+        // 修改 lessOptions 配置
+        config.lessOptions = {
+          javascriptEnabled: false,
+        };
       },
     },
   },
 };
 ```
 
-### Function 类型
+### 并行编译
 
-当 `tools.less` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+Less 编译是纯 JavaScript 计算，默认只占用 Node.js 主线程。开启 `parallel` 后，Less 模块会分发到 worker 线程池中编译，项目里 Less 文件较多时可以缩短构建时间。
 
 ```js
 export default {
   tools: {
-    less(config) {
-      // 修改 lessOptions 配置
-      config.lessOptions = {
-        javascriptEnabled: false,
-      };
+    less: {
+      parallel: true,
     },
   },
 };
 ```
 
+:::tip
+传给 worker 线程的选项需要满足[结构化克隆算法](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)的要求，因此开启 `parallel` 后，`lessLoaderOptions` 中不能包含函数，例如 `additionalData` 函数或自定义的 `implementation`。
+:::
+
 ### 修改 Less 版本
 
 在某些场景下，如果你需要使用特定的 Less 版本，而不是使用 Modern.js 内置的 Less v4，可以在项目中安装需要使用的 Less 版本，并通过 `less-loader` 的 `implementation` 选项设置。
@@ -60,7 +89,9 @@ export default {
 export default {
   tools: {
     less: {
-      implementation: require('less'),
+      lessLoaderOptions: {
+        implementation: require('less'),
+      },
     },
   },
 };
@@ -77,10 +108,54 @@ export default {
 ```js
 export default {
   tools: {
-    less(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    less: {
+      lessLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+推荐直接使用插件的 `exclude` 选项，效果相同：
+
+```js
+export default {
+  tools: {
+    less: {
+      exclude: /node_modules/,
     },
   },
 };
 ```
 
+### 兼容旧写法
+
+:::warning 不要混写两种层级
+同一个对象里只要出现插件顶层键（`lessLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.less: { parallel: true, lessOptions: { ... } }` 里的 `lessOptions` 会被忽略，必须移到 `lessLoaderOptions` 下；开发环境下会打印一条提示。
+:::
+
+
+在之前的版本中，`tools.less` 的取值直接是 less-loader 的选项，例如 `tools.less: { lessOptions: {} }` 或 `tools.less(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `lessLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
+
+```js
+// 旧写法
+export default {
+  tools: {
+    less: {
+      lessOptions: { javascriptEnabled: false },
+    },
+  },
+};
+
+// 新写法
+export default {
+  tools: {
+    less: {
+      lessLoaderOptions: {
+        lessOptions: { javascriptEnabled: false },
+      },
+    },
+  },
+};
+```

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

@@ -9,39 +9,64 @@ title: sass
 
 ```js
 const defaultOptions = {
-  // 默认在开发环境下启用 CSS 的 Source Map
-  sourceMap: isDev,
+  sassLoaderOptions: {
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
+  },
 };
 ```
 
-你可以通过 `tools.sass` 修改 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的配置。
+`tools.sass` 用于修改 [@rsbuild/plugin-sass](https://rsbuild.rs/plugins/list/plugin-sass) 的选项，取值为该插件的完整选项：
+
+| 选项                 | 说明                                                                               |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| `sassLoaderOptions`  | 传给 [sass-loader](https://github.com/webpack-contrib/sass-loader) 的选项，支持对象或函数 |
+| `include`            | 指定哪些文件交给 sass-loader 处理，默认 `/\.s(?:a|c)ss$/`                             |
+| `exclude`            | 指定哪些文件不交给 sass-loader 处理                                                  |
+| `rewriteUrls`        | 是否使用 resolve-url-loader 重写 Sass 文件中的相对 URL，默认 `true`                    |
 
-### Object 类型
+### 修改 sass-loader 选项
 
-当 `tools.sass` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
+`sassLoaderOptions` 为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`sassOptions` 会通过 deepMerge 进行深层合并。
 
 ```js
 export default {
   tools: {
     sass: {
-      sourceMap: true,
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
     },
   },
 };
 ```
 
-### Function 类型
+`sassLoaderOptions` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions(config) {
+        // 修改 additionalData 配置
+        config.additionalData = async (content, loaderContext) => {
+          // ...
+        };
+      },
+    },
+  },
+};
+```
 
-当 `tools.sass` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+### 关闭 URL 重写
+
+默认情况下，Sass 文件里的相对 URL 会经过 resolve-url-loader 重写为相对于源文件的路径。如果项目不依赖这一行为，可以关闭它来减少一个 loader：
 
 ```js
 export default {
   tools: {
-    sass(config) {
-      // 修改 sourceMap 配置
-      config.additionalData = async (content, loaderContext) => {
-        // ...
-      };
+    sass: {
+      rewriteUrls: false,
     },
   },
 };
@@ -55,7 +80,9 @@ export default {
 export default {
   tools: {
     sass: {
-      implementation: require('sass'),
+      sassLoaderOptions: {
+        implementation: require('sass'),
+      },
     },
   },
 };
@@ -72,8 +99,53 @@ export default {
 ```js
 export default {
   tools: {
-    sass(config, { addExcludes }) {
-      addExcludes(/node_modules/);
+    sass: {
+      sassLoaderOptions(config, { addExcludes }) {
+        addExcludes(/node_modules/);
+      },
+    },
+  },
+};
+```
+
+推荐直接使用插件的 `exclude` 选项，效果相同：
+
+```js
+export default {
+  tools: {
+    sass: {
+      exclude: /node_modules/,
+    },
+  },
+};
+```
+
+### 兼容旧写法
+
+:::warning 不要混写两种层级
+同一个对象里只要出现插件顶层键（`sassLoaderOptions`、`include`、`exclude` 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 `tools.sass: { rewriteUrls: false, sassOptions: { ... } }` 里的 `sassOptions` 会被忽略，必须移到 `sassLoaderOptions` 下；开发环境下会打印一条提示。
+:::
+
+
+在之前的版本中，`tools.sass` 的取值直接是 sass-loader 的选项，例如 `tools.sass: { sassOptions: {} }` 或 `tools.sass(config, { addExcludes }) {}`。这种写法目前仍然生效，Modern.js 会自动把它包装为 `sassLoaderOptions`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。
+
+```js
+// 旧写法
+export default {
+  tools: {
+    sass: {
+      sourceMap: true,
+    },
+  },
+};
+
+// 新写法
+export default {
+  tools: {
+    sass: {
+      sassLoaderOptions: {
+        sourceMap: true,
+      },
     },
   },
 };

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

@@ -0,0 +1,93 @@
+---
+title: svgr
+---
+
+# tools.svgr
+
+- **类型：** `Object | Function | false`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  mixedImport: true,
+  svgrOptions: {
+    exportType: 'named',
+  },
+};
+```
+
+`tools.svgr` 用于修改 [@rsbuild/plugin-svgr](https://rsbuild.rs/plugins/list/plugin-svgr) 的选项，取值为该插件的完整选项。设置为 `false` 时不再注册 SVGR 插件，所有 `.svg` 文件按静态资源处理。
+
+| 选项              | 说明                                                                                          |
+| ----------------- | --------------------------------------------------------------------------------------------- |
+| `svgrOptions`     | 传给 [SVGR](https://react-svgr.com/docs/options/) 的参数，例如 `exportType`、`icon`、`svgoConfig` |
+| `parallel`        | 是否使用 worker 线程并行转换 SVG，默认 `false`                                                  |
+| `exclude`         | 指定哪些 SVG 文件不交给 SVGR 处理                                                              |
+| `excludeImporter` | 指定从哪些文件导入 SVG 时不交给 SVGR 处理                                                       |
+| `query`           | 指定触发 SVGR 转换的 query，默认 `/react/`                                                     |
+| `mixedImport`     | 是否允许在同一个模块中同时导入 URL 与 React 组件，默认 `true`                                   |
+
+### 合并规则
+
+`tools.svgr` 为 `Object` 类型时，顶层字段与默认配置通过 Object.assign 进行浅层合并，`svgrOptions` 会再合并一层，因此只设置 `svgrOptions.icon` 不会丢掉默认的 `exportType`。
+
+`tools.svgr` 为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。也支持传入由对象和函数组成的数组，按顺序依次应用。
+
+### 并行转换
+
+SVGR 转换是纯 JavaScript 计算，默认只占用 Node.js 主线程。项目里 SVG 文件较多时，开启 `parallel` 可以把转换分发到 worker 线程池：
+
+```js
+export default {
+  tools: {
+    svgr: {
+      parallel: true,
+    },
+  },
+};
+```
+
+:::tip
+传给 worker 线程的选项需要满足[结构化克隆算法](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)的要求，因此开启 `parallel` 后，`svgrOptions` 中不能包含函数。
+:::
+
+### 修改默认导出
+
+`svgrOptions.exportType` 决定 SVG 文件默认导出的内容：`'named'` 表示默认导出是文件 URL，React 组件通过 `ReactComponent` 具名导出；`'default'` 表示默认导出就是 React 组件。
+
+```js
+export default {
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
+  },
+};
+```
+
+### 关闭 SVGR
+
+如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用，可以关闭 SVGR 以提升构建性能：
+
+```js
+export default {
+  tools: {
+    svgr: false,
+  },
+};
+```
+
+### 与旧配置的关系
+
+`tools.svgr` 取代了下面两个已废弃的配置项，二者目前仍然生效，并将在下一个大版本中移除：
+
+| 旧配置                                | 新配置                                            |
+| ------------------------------------- | ------------------------------------------------- |
+| `output.svgDefaultExport: 'component'` | `tools.svgr: { svgrOptions: { exportType: 'default' } }` |
+| `output.svgDefaultExport: 'url'`       | `tools.svgr: { svgrOptions: { exportType: 'named' } }`   |
+| `output.disableSvgr: true`             | `tools.svgr: false`                               |
+| `output.disableSvgr: false`            | 默认行为，直接删除即可                            |
+
+同时设置时以 `tools.svgr` 为准：显式设置了 `tools.svgr` 后，`output.disableSvgr` 不再生效；`tools.svgr.svgrOptions.exportType` 会覆盖 `output.svgDefaultExport` 派生的值。

package/docs/zh/guides/basic-features/static-assets/svg-assets.mdx

@@ -42,16 +42,22 @@ export default () => <Logo />;
 
 ## 修改默认导出
 
-你可以通过 [output.svgDefaultExport](/configure/app/output/svg-default-export) 配置项来修改 SVG 文件默认导出的内容，比如把默认导出的内容设置为 React 组件：
+你可以通过 [tools.svgr](/configure/app/tools/svgr) 的 `svgrOptions.exportType` 来修改 SVG 文件默认导出的内容，比如把默认导出的内容设置为 React 组件：
 
 ```ts
 export default {
-  output: {
-    svgDefaultExport: 'component',
+  tools: {
+    svgr: {
+      svgrOptions: {
+        exportType: 'default',
+      },
+    },
   },
 };
 ```
 
+旧的 [output.svgDefaultExport](/configure/app/output/svg-default-export) 配置项仍然生效，但已废弃。
+
 此时再使用默认导入，你会得到一个 React 组件，而不是 URL：
 
 ```tsx title="src/component/Logo.tsx"
@@ -80,12 +86,12 @@ export default () => <Logo />;
 
 默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。
 
-如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 [disableSvgr](/configure/app/output/disable-svgr) 设置为 true 来关闭此项转换，以提升构建性能。
+如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 [tools.svgr](/configure/app/tools/svgr) 设置为 `false` 来关闭此项转换，以提升构建性能。
 
 ```js
 export default {
-  output: {
-    disableSvgr: true,
+  tools: {
+    svgr: false,
   },
 };
 ```
@@ -153,21 +159,27 @@ declare module '*.svg' {
 }
 ```
 
-如果需要修改 SVGR 配置，可通过如下方式：
+如果需要修改 SVGR 配置，可通过 [tools.svgr](/configure/app/tools/svgr) 的 `svgrOptions` 设置。传入的 `svgoConfig.plugins` 会按插件名与默认配置深度合并，因此只需写出要改动的部分：
 
 ```js
 export default {
   tools: {
-    bundlerChain: (chain, { CHAIN_ID }) => {
-      chain.module
-        .rule(CHAIN_ID.RULE.SVG)
-        .oneOf(CHAIN_ID.ONE_OF.SVG)
-        .use(CHAIN_ID.USE.SVGR)
-        .tap(options => {
-          // modify svgoConfig
-          options.svgoConfig.plugins[0].params.overrides.removeUselessDefs = false;
-          return options;
-        });
+    svgr: {
+      svgrOptions: {
+        svgoConfig: {
+          plugins: [
+            {
+              name: 'preset-default',
+              params: {
+                overrides: {
+                  // 在默认的 preset-default 之上追加一项 override
+                  removeUselessDefs: false,
+                },
+              },
+            },
+          ],
+        },
+      },
     },
   },
 };

package/docs/zh/plugin/introduction.mdx

@@ -129,7 +129,7 @@ Rsbuild 是 Modern.js 底层的构建工具，通过添加 Rsbuild 插件可修
 | 插件                                                                                 | 介绍                                                                                   | Modern.js 链接                                                                                                                        |
 | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | [React 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-react)                        | 提供对 React 的支持                                                                    | -                                                                                                                                     |
-| [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr)                          | 支持将 SVG 图片转换为一个 React 组件                                                   | [output.disableSvgr](/configure/app/output/disable-svgr)<br />[output.svgDefaultExport](/configure/app/output/svg-default-export)     |
+| [SVGR 插件](https://v2.rsbuild.rs/zh/plugins/list/plugin-svgr)                          | 支持将 SVG 图片转换为一个 React 组件                                                   | [tools.svgr](/configure/app/tools/svgr)     |
 | [Assets Retry 插件](https://github.com/rstackjs/rsbuild-plugin-assets-retry)          | 用于在静态资源加载失败时自动发起重试请求                                               | [output.assetsRetry](/configure/app/output/assets-retry.html)                                                                         |
 | [Type Check 插件](https://github.com/rstackjs/rsbuild-plugin-type-check)             | 用于在单独的进程中运行 TypeScript 类型检查                                             | [output.disableTsChecker](/configure/app/output/disable-ts-checker.html)<br />[tools.tsChecker](/configure/app/tools/ts-checker.html) |
 | [Source Build 插件](https://github.com/rstackjs/rsbuild-plugin-source-build)   | 用于 monorepo 场景，支持引用其他子目录的源代码，并完成构建和热更新                     | [experiments.sourceBuild](/configure/app/experiments/source-build.html)                                                               |

package/package.json

@@ -16,14 +16,14 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.9.2",
+  "version": "3.9.3",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "3.9.2"
+    "@modern-js/sandpack-react": "3.9.3"
   },
   "devDependencies": {
     "rsbuild-plugin-open-graph": "1.1.3",