@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.8 → 3.9.3-ultramodern.1

package/docs/en/guides/get-started/ultramodern.mdx

@@ -51,13 +51,46 @@ UltraModern.js uses Effect HttpApi, TanStack Router, SSR, and independently depl
 ## Create and Validate a Workspace
 
 ```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create@latest catalog --vertical
+pnpm dlx @bleedingdev/modern-js-ultramodern-create@<V> my-workspace --renderer react
+cd my-workspace
 mise install
 mise exec -- pnpm install
 mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+Replace `<V>` with the published framework version. Omit `--renderer` to use
+React, or select `solid` or `octane` during initial generation. Add commands
+read the application's `modern.config.ts` instead of accepting `--renderer`.
+
+### Select the application renderer
+
+Use the fork's config entrypoint; it owns the selected plugin composition:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/ultramodern-app-tools';
+
+export default defineConfig({
+  renderer: 'solid', // 'react' or 'octane'; omitted means 'react'
+  server: { ssr: true },
+});
+```
+
+Solid 2.0.0-rc.13 and Octane are Node previews for CSR, native streaming SSR,
+hydration and managed filesystem routes. Use Node 26.7.0 or newer. Author
+components with `solid-js` / `@solidjs/web` or `octane`, and import native router
+primitives from `@modern-js/renderer-solid/router` or
+`@modern-js/renderer-octane/router`. Generated entries own mounting and hydration.
+Changing the selector requires matching native source and dependencies, a
+dev-server restart and a document reload.
+
+Native previews reject workers, Module Federation, RSC, SSG, React i18n
+integration, SVG component imports and CSS declaration emission beside authored
+source. SVG URLs remain supported. The
+[application tools README](https://github.com/BleedingDev/ultramodern.js/tree/main/packages/solutions/ultramodern-app-tools#readme)
+defines the current preview profile and pinned dependencies. The federation,
+i18n and Cloudflare examples below describe the React profile.
+
 Localized Cloudflare SSR workspaces redirect `/` on the server to the negotiated locale. For example, `Accept-Language: cs-CZ` returns `302` with `Location: /cs`, `Cache-Control: private, no-store`, and `Vary` covering locale detection headers. Validate the deployed Worker with:
 
 ```bash
@@ -65,26 +98,24 @@ curl -I -H 'Accept-Language: cs-CZ,cs;q=0.9,en;q=0.1' https://<worker-host>/
 ```
 
 Generated strict Effect workspaces pin the compatible Effect cohort with pnpm
-overrides: `effect@4.0.0-rc.112`, `@effect/opentelemetry@4.0.0-rc.112`,
-and `@effect/vitest@4.0.0-rc.112`. Do not add app-local direct Effect
+overrides: `effect@4.0.0-rc.117`, `@effect/opentelemetry@4.0.0-rc.117`,
+and `@effect/vitest@4.0.0-rc.117`. Do not add app-local direct Effect
 versions that disagree with those overrides. The strict 24-hour release-age
 gate applies to installed packages; this cohort carries no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval
-target. Independently, exact `trustPolicyExclude` entries for `effect`
-and `@effect/opentelemetry` cover their trusted-publisher to provenance
-metadata transition; they are not release-age approvals.
+target.
 
 ### Current generated dependency baseline
 
 | Surface | Pin |
 | --- | --- |
-| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.112` |
-| Effect compiler | `@effect/tsgo@0.41.0` |
-| Oxc and Ultracite | `oxlint@1.81.0`, `oxfmt@0.66.0`, `ultracite@7.11.0` |
-| TanStack Router | `@tanstack/react-router@1.170.33`, `@tanstack/router-core@1.171.28`, `@tanstack/history@1.162.2` |
-| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.9.0`; `@module-federation/node@2.7.50` |
+| Effect runtime and test cohort | `effect`, `@effect/opentelemetry`, and `@effect/vitest`: `4.0.0-rc.117` |
+| Effect compiler | `@effect/tsgo@0.45.0` |
+| Oxc and Ultracite | `oxlint@1.85.0`, `oxfmt@0.70.0`, `ultracite@7.12.0` |
+| TanStack Router | `@tanstack/react-router@1.170.41`, `@tanstack/router-core@1.171.34`, `@tanstack/history@1.162.4` |
+| Module Federation | `bridge-react`, `manifest`, `modern-js-v3`, and `rspack`: `2.9.2`; `@module-federation/node@2.7.52` |
 | Tailwind CSS | `tailwindcss@4.3.3` |
-| Node and package tooling | Node `26.7.0`, `@types/node@^26.4.1`, pnpm `11.24.0` |
+| Node and package tooling | Node `26.7.0`, `@types/node@^26.6.2`, pnpm `11.27.1` |
 
 Generated workspaces default to Module Federation bridge-react's router-free
 base entry (`bridge.enableBridgeRouter: false`), with TanStack Router as the
@@ -178,11 +209,11 @@ compilers do not share mutable build state.
 
 ## Configure the public preset
 
-Use `presetUltramodern(appConfig, presetOptions)` inside the normal Modern.js
+Use `presetUltramodern(appConfig, presetOptions)` inside the UltraModern
 `defineConfig` call:
 
 ```ts title="modern.config.ts"
-import { defineConfig, presetUltramodern } from '@modern-js/app-tools';
+import { defineConfig, presetUltramodern } from '@modern-js/ultramodern-app-tools';
 
 export default defineConfig(
   presetUltramodern(

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/en/plugin/server-plugins/api.mdx

@@ -191,6 +191,7 @@ Adds additional logic when the server resets.
       - `'file-change'`: File change event
     - `event.payload`: When `type` is `'file-change'`, contains an array of file change information.
 - **Execution Phase:** When files change or repack is needed.
+- **Repack Order:** On `'repack'` the dev server awaits the handlers in registration order before it purges the previous server bundle from the require cache. A rejecting handler skips the handlers after it. New requests wait until the handlers settle; requests already running keep the modules they loaded. A repack handler must not await a request to the dev server, because that request waits for the handler.
 - **Example:**
 
 ```typescript

package/docs/zh/components/deploy-command.mdx

@@ -8,6 +8,7 @@ Usage: modern deploy [options]
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -s --skip-build       跳过构建阶段
+  --deploy-target <target>  部署目标（node、vercel、netlify、ghPages、cloudflare），优先于 deploy.target 和 MODERNJS_DEPLOY
   -h, --help            显示命令帮助
 ```
 

package/docs/zh/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-mise use pnpm@11.24.0
+mise use pnpm@11.27.1
 ```
 
 :::note

package/docs/zh/configure/app/bff/effect.mdx

@@ -52,7 +52,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 `/effect-client` 之前，请安装精确版本的依赖组：
 
 ```bash
-pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
+pnpm add effect@4.0.0-rc.117 @effect/opentelemetry@4.0.0-rc.117
 ```
 
 采用精确版本是因为 UltraModern 以锁步依赖组的方式发布 Effect。只使用
@@ -221,23 +221,16 @@ UltraModern 生成的 workspace 会通过 `pnpm-workspace.yaml` overrides 锁定
 Effect 版本组。当前 UltraModern 版本组使用：
 
 ```yaml
-trustPolicyExclude:
-  - 'effect@4.0.0-rc.112'
-  - '@effect/opentelemetry@4.0.0-rc.112'
-
 overrides:
-  '@effect/opentelemetry': 4.0.0-rc.112
-  '@effect/vitest': 4.0.0-rc.112
-  effect: 4.0.0-rc.112
+  '@effect/opentelemetry': 4.0.0-rc.117
+  '@effect/vitest': 4.0.0-rc.117
+  effect: 4.0.0-rc.117
 ```
 
 不要在应用包里添加不同版本的直接 `effect` 依赖。Effect 预发布版本不一致时，Layer 或 HTTP
 middleware 构建可能因为运行时 service 来自不同包实例而失败。严格的 24 小时发布年龄
 门禁适用于实际安装的包；当前版本组没有 Effect 年龄豁免，且仅用于 override 的
 `@effect/vitest` 不是已安装的审批目标。
-`trustPolicyExclude` 是另一项独立策略：其中精确的 `effect` 与
-`@effect/opentelemetry` 例外用于处理 trusted-publisher metadata 向 provenance
-attestation 的迁移，并不等同于 release-age 审批。
 
 ## 契约测试
 

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/source/react-compiler.mdx

@@ -11,6 +11,8 @@ title: reactCompiler
 
 Modern.js 基于 Rspack `builtin:swc-loader` 内置的 Rust 版 React Compiler 实现该能力（等价于设置 SWC 的 `jsc.transform.reactCompiler`），复用 Rspack 内置的 SWC 转换链，无需额外引入 Babel。
 
+该编译仅作用于浏览器环境（`output.target: 'web'`）。服务端环境（`node`、`web-worker` SSR Worker 以及 BFF 代码）每次请求只渲染一次，无法从自动记忆化中获益，因此不会被编译。
+
 :::tip
 该配置默认关闭，任何 React 版本下都需要显式开启，包括 React 19。
 :::

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/configure/app/tools/ts-checker.mdx

@@ -80,24 +80,10 @@ export default {
 
 类型检查默认使用 [TypeScript Go](https://github.com/microsoft/typescript-go)（`tsgo`）。该能力由 [`@rsbuild/plugin-type-check`](https://github.com/rstackjs/rsbuild-plugin-type-check) 底层集成的 [`ts-checker-rspack-plugin`](https://github.com/rstackjs/ts-checker-rspack-plugin) 提供，可以将类型检查耗时减少约 5-10 倍。
 
-Modern.js 会优先使用项目内稳定版 `typescript`（TypeScript 7 或更新版本），仍在预览通道的项目会回退到 `@typescript/native-preview`。如需固定稳定版 TypeScript 7，可在项目中安装：
+Modern.js 使用稳定版 `typescript@7.0.2` 提供的原生 Go 编译器，先解析项目内的包，再解析构建器声明的依赖，并拒绝不兼容的版本。可在项目中安装受支持的编译器：
 
-<PackageManagerTabs command="install typescript -D" />
+<PackageManagerTabs command="install typescript@7.0.2 -D" />
 
-开启 `tsgo` 后，TypeScript 7 项目默认的 `typescript.typescriptPath` 会解析到 `typescript/package.json`。如果你手动设置了 `typescript.typescriptPath`，它必须是指向 `typescript/package.json` 或 `@typescript/native-preview/package.json` 的绝对路径。
-
-如需回退到经典 TypeScript 检查器，请将 `typescript.tsgo` 设置为 `false`，并确保项目中安装了 `typescript`：
-
-```ts
-export default {
-  tools: {
-    tsChecker: {
-      typescript: {
-        tsgo: false,
-      },
-    },
-  },
-};
-```
+默认的 `typescript.typescriptPath` 会解析为该稳定版编译器的 `typescript/package.json` 绝对路径。
 
 关于 `tsgo` 模式下生效的配置项和相关限制，请参考 [ts-checker-rspack-plugin - TypeScript Go support](https://github.com/rstackjs/ts-checker-rspack-plugin#typescript-go-support)。