@modern-js/main-doc 3.0.0-alpha.1 → 3.0.0-alpha.2

package/docs/en/apis/app/runtime/router/router.mdx

@@ -64,7 +64,7 @@ interface Location extends Path {
 The `useLocation` hook returns the current [location](https://reactrouter.com/web/api/location) object. A new location object would be returned whenever the current location changes.
 
 ```ts
-import { useLocation } from "@modern-js/runtime/router";
+import { useLocation } from '@modern-js/runtime/router';
 
 function usePageViews() {
   let location = useLocation();

package/docs/en/apis/app/runtime/ssr/renderStreaming.mdx

@@ -4,7 +4,7 @@ title: renderStreaming
 
 # renderStreaming
 
-Used for React v18+ Streaming SSR to render readable streams, used in conjunction with `createRequestHandler`.
+Used for `React v18` + `Streaming SSR` to render readable streams, used in conjunction with `createRequestHandler`.
 
 ## Usage
 
@@ -12,9 +12,10 @@ Used for React v18+ Streaming SSR to render readable streams, used in conjunctio
 import {
   renderStreaming,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const stream = await renderStreaming(request, <ServerRoot />, options);
 
   return new Response(stream, {
@@ -43,9 +44,10 @@ export type RenderStreaming = (
 import {
   renderStreaming,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const stream = await renderStreaming(request, <ServerRoot />, options);
 

package/docs/en/apis/app/runtime/ssr/renderString.mdx

@@ -12,9 +12,10 @@ Used for React String SSR to render strings, used in conjunction with `createReq
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {
@@ -43,9 +44,10 @@ export type RenderString = (
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const body = await renderString(request, <ServerRoot />, options);
 

package/docs/en/apis/app/runtime/ssr/requestHandler.mdx

@@ -12,9 +12,10 @@ Used to customize the Server-Side Rendering entry to return the `requestHandler`
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

package/docs/en/configure/_meta.json

@@ -73,5 +73,6 @@
     "label": "experiments",
     "collapsed": true
   },
-  "app/builder-plugins"
+  "app/builder-plugins",
+  "app/split-chunks"
 ]

package/docs/en/configure/app/output/dist-path.mdx

@@ -4,6 +4,11 @@ title: distPath
 
 # output.distPath
 
+
+import CommentTips from '@site-docs/components/output-distpath-warning';
+
+<CommentTips />
+
 - **Type：**
 
 ```ts

package/docs/en/configure/app/runtime/router.mdx

@@ -4,26 +4,26 @@ title: router
 
 # router
 
-- **Type:** `boolean | Object`
-- **Default:** `false`
+- **Type:** `Object`
+- **Default:** `{}`
 
-This value is set to `true` when the project is created, supporting the use of [conventional routing](/guides/concept/entries.html#约定式路由) provided by Modern.js for routing management.
-
-If you wish to use [controlled routing](/guides/concept/entries.html#自控式路由), please remove this value or set it to `false`.
+This configuration item is used to configure client-side routing, supporting the use of [conventional routing](/guides/concept/entries.html#convention-routing) provided by Modern.js for routing management.
 
 :::note
-All sub-configurations of `router` will only take effect when using conventional routing.
+The `router` configuration item **only takes effect when using conventional routing entries** (i.e., when there is a `routes/` directory in the entry). For controlled routing entries or custom entries, this configuration will not take effect.
+
+In multi-entry applications, you can configure different routing behaviors for different entries using the function form of `defineRuntimeConfig`. For more details, see [Runtime Configuration Introduction](/configure/app/runtime/0-intro#multi-entry-configuration).
 :::
 
 ## basename
 
 - **Type:** `string`
-- **Default:** ``
+- **Default:** `/`
 
-The basename option specifies the subpath where the app is deployed, for situations where it cannot be deployed to the root domain.
+Sets the `basename` for client-side routing, typically used when the application needs to be deployed under a non-root path of the domain.
 
 :::tip
-推荐使用 [`server.baseUrl`](/configure/app/server/base-url) 进行配置。
+It is recommended to use [`server.baseUrl`](/configure/app/server/base-url) for configuration.
 :::
 
 ## supportHtml5History

package/docs/en/configure/app/split-chunks.mdx

@@ -0,0 +1,17 @@
+# splitChunks
+
+- **Type:**
+
+```ts
+type SplitChunksConfig =
+  | (Rspack.OptimizationSplitChunksOptions & {
+      preset?: SplitChunksPreset;
+    })
+  | false;
+```
+
+`splitChunks` is used to configure Rsbuild's chunk splitting strategy.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="splitChunks" />

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

@@ -1,5 +1,4 @@
 [
-  "rspack-start",
   {
     "type": "dir",
     "name": "bff",

package/docs/en/guides/advanced-features/build-performance.mdx

@@ -16,10 +16,6 @@ The strategies in [Bundle Size Optimization](/guides/advanced-features/page-perf
 
 The following are some general optimization strategies, which can speed up the development build and production build, and some of them also optimize the bundle size.
 
-### Using Rspack (recommended)
-
-If you are not using Rspack yet, you can switch to Rspack build mode to improve the build speed by 5~10 times, see [Using Rspack](/guides/advanced-features/rspack-start.html) for more information.
-
 ### Upgrade Node.js version
 
 In general, updating Node.js to the latest [LTS release](https://github.com/nodejs/release#release-schedule) will help improve build performance.

package/docs/en/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -99,18 +99,3 @@ See details in [plugin-image-compress](https://github.com/rspack-contrib/rsbuild
 A great chunk splitting strategy is very important to improve the loading performance of the application. It can make full use of the browser's caching mechanism to reduce the number of requests and improve the loading speed of the application.
 
 A variety of [chunk splitting strategies](https://rsbuild.rs/guide/optimization/split-chunk) are built into Modern.js, which can meet the needs of most applications. You can also customize the chunk splitting config according to your own business scenarios.
-
-For example, split the `axios` library under node_modules into `axios.js`:
-
-```js
-export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'split-by-experience',
-      forceSplitting: {
-        axios: /node_modules\/axios/,
-      },
-    },
-  },
-};
-```

package/docs/en/guides/advanced-features/page-performance/react-compiler.mdx

@@ -30,20 +30,23 @@ npm install babel-plugin-react-compiler
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
+import { pluginBabel } from '@rsbuild/plugin-babel';
 
 export default defineConfig({
-  tools: {
-    babel(_, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-react-compiler',
+  builderPlugins: [
+    pluginBabel({
+      babelLoaderOptions: (config, { addPlugins }) => {
+        addPlugins([
+          [
+            'babel-plugin-react-compiler',
           {
-            target: '18', // or '17', depending on your React version
+            target: '18', // 或 '17'，根据你使用的 React 版本
           },
-        ],
-      ]);
-    },
-  },
+          ],
+        ]);
+      },
+    });
+  ];
   plugins: [appTools()],
 });
 ```

package/docs/en/guides/basic-features/render/streaming-ssr.mdx

@@ -229,13 +229,30 @@ function ErrorElement() {
 }
 ```
 
-## Waiting for All Content to Load for Crawlers
+## Controlling When to Wait for Full HTML
 
-Streaming can enhance user experience by allowing users to perceive content as it becomes available.
+Streaming improves perceived speed, but in some cases (SEO crawlers, A/B buckets, compliance pages) you may want to wait for all content before sending the response.
 
-However, when a crawler visits the page, it might need to load all content and output the entire HTML at once, rather than progressively loading it.
+Modern.js decides the streaming mode with this priority:
 
-Modern.js uses [isbot](https://www.npmjs.com/package/isbot) to determine if a request is from a crawler based on the `user-agent` header.
+1. Request header `x-should-stream-all` (set per-request in middleware).
+2. Env `MODERN_JS_STREAM_TO_STRING` (forces full HTML).
+3. [isbot](https://www.npmjs.com/package/isbot) check on `user-agent` (bots get full HTML).
+4. Default: stream shell first.
+
+Set the header in your middleware to choose the behavior dynamically:
+
+```ts title="middleware example"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll = /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // Write a boolean string: true -> onAllReady, false -> onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
 
 import StreamSSRPerformance from '@site-docs-en/components/stream-ssr-performance';
 

package/docs/en/guides/troubleshooting/builder.mdx

@@ -56,19 +56,7 @@ Under normal circumstances, Modern.js will not use Babel to compile CommonJS mod
 There are two workarounds for this problem:
 
 1. Avoid adding CommonJS modules to Babel compilation.
-2. Set Babel's `sourceType` configuration option to `unambiguous`, for example:
-
-```js
-export default {
-  tools: {
-    babel(config) {
-      config.sourceType = 'unambiguous';
-    },
-  },
-};
-```
-
-Setting `sourceType` to `unambiguous` may have some other effects, please refer to [Babel official documentation](https://babeljs.io/docs/en/options#sourcetype).
+2. Set Babel's `sourceType` configuration to `unambiguous`.
 
 ---
 
@@ -93,63 +81,8 @@ When the compilation progress bar is stuck, but there is no Error log on the ter
 If this problem occurs after you modify the Babel config, it is recommended to check for the following incorrect usages:
 
 1. You have configured a plugin or preset that does not exist, maybe the name is misspelled, or it is not installed correctly.
-
-```ts
-// wrong example
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      // The plugin has the wrong name or is not installed
-      addPlugins('babel-plugin-not-exists');
-    },
-  },
-};
-```
-
 2. Whether multiple babel-plugin-imports are configured, but the name of each babel-plugin-import is not declared in the third item of the array.
 
-```ts
-// wrong example
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd', libraryDirectory: 'es' },
-        ],
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
-        ],
-      ]);
-    },
-  },
-};
-```
-
-```ts
-// correct example
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd', libraryDirectory: 'es' },
-          'antd',
-        ],
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
-          'antd-mobile',
-        ],
-      ]);
-    },
-  },
-};
-```
-
 ---
 
 ### Compilation error after referencing a type from lodash

package/docs/en/plugin/cli-plugins/api.mdx

@@ -47,7 +47,7 @@ Gets the context information of the Modern.js application.
 | `isProd`               | `boolean`           | Whether it is in production mode                                 | -                            |
 | `appDirectory`         | `string`            | The absolute path to the project root directory                  | -                            |
 | `srcDirectory`         | `string`            | The absolute path to the project source code directory           | -                            |
-| `distDirectory`        | `string`            | The absolute path to the project output directory                | After `modifyResolvedConfig` |
+| `distDirectory`        | `string`            | The absolute path to the project output directory                | In `onPrepare` (and later)   |
 | `sharedDirectory`      | `string`            | The absolute path to the shared modules directory                | -                            |
 | `nodeModulesDirectory` | `string`            | The absolute path to the `node_modules` directory                | -                            |
 | `ip`                   | `string`            | The IPv4 address of the current machine                          | -                            |
@@ -106,18 +106,13 @@ api.onPrepare(() => {
 Gets the final configuration after internal processing by Modern.js and modifications by plugins (normalized configuration).
 
 - **Returns:** The normalized configuration object.
-- **When Available:** Must be used after the `modifyResolvedConfig` hook.
+- **When Available:** Must be used in `onPrepare` (and later hooks, such as `onBeforeBuild`).
 - **Example:**
 
 ```typescript
-api.modifyResolvedConfig(resolvedConfig => {
-  // ... Modify the configuration ...
-  return resolvedConfig;
-});
-
-api.onBeforeBuild(() => {
+api.onPrepare(() => {
   const finalConfig = api.getNormalizedConfig();
-  console.log('Final build configuration:', finalConfig);
+  console.log('Final configuration:', finalConfig);
 });
 ```
 

package/docs/zh/apis/app/hooks/config/upload.mdx

@@ -36,7 +36,7 @@ export default () => {
 };
 ```
 
-另外，不论是在[自定义 HTML](/guides/basic-features/html) 中，或是在 [`config/public/`](/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
+另外，不论是在 [自定义 HTML](/guides/basic-features/html) 中，或是在 [`config/public/`](/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
 
 ```html
 <script src="/upload/index.js"></script>

package/docs/zh/apis/app/hooks/src/app.mdx

@@ -5,7 +5,7 @@ sidebar_position: 1
 
 # App.[tj]sx
 
-应用使用[自控路由](/guides/concept/entries.html#自控式路由)时的入口标识符。
+应用使用 [自控路由](/guides/concept/entries.html#自控式路由) 时的入口标识符。
 
 `App.[tj]sx` 并不是实际的应用入口，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下：
 
@@ -28,7 +28,7 @@ const ModernRoot = createRoot();
 render(<ModernRoot />, 'root');
 ```
 
-`createRoot` 执行时，会去获取注册的 Globa App，生成真实的 React 组件。
+`createRoot` 执行时，会去获取注册的 Global App，生成真实的 React 组件。
 
 :::note
 在多入口的场景下，每个入口都可以拥有独立的 `App.[jt]sx`，详见[入口](/guides/concept/entries)。

package/docs/zh/apis/app/hooks/src/routes.mdx

@@ -4,7 +4,7 @@ sidebar_position: 2
 ---
 # routes/
 
-应用使用[约定式路由](/guides/basic-features/routes/routes#约定式路由)时的入口标识。
+应用使用 [约定式路由](/guides/basic-features/routes/routes#约定式路由) 时的入口标识。
 
 约定式路由以 `routes/` 为约定的入口， 会分析 `src/routes` 目录下的文件得到客户端路由配置。
 

package/docs/zh/apis/app/runtime/router/router.mdx

@@ -63,7 +63,7 @@ interface Location extends Path {
 `useLocation` 返回当前 url 对应的 [location](https://reactrouter.com/web/api/location) 对象。每当路由更新的时候，都会拿到一个新的 `location` 对象。
 
 ```ts
-import { useLocation } from "@modern-js/runtime/router";
+import { useLocation } from '@modern-js/runtime/router';
 
 function usePageViews() {
   let location = useLocation();

package/docs/zh/apis/app/runtime/ssr/renderStreaming.mdx

@@ -4,7 +4,7 @@ title: renderStreaming
 
 # renderStreaming
 
-用于 React v18+ Streaming SSR 渲染出可读流, 配合 `createRequestHandler` 使用
+用于 `React v18` + `Streaming SSR` 渲染出可读流, 配合 `createRequestHandler` 使用
 
 ## 使用
 
@@ -12,9 +12,10 @@ title: renderStreaming
 import {
   renderStreaming,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const stream = await renderStreaming(request, <ServerRoot />, options);
 
   return new Response(stream, {
@@ -43,9 +44,10 @@ export type RenderStreaming = (
 import {
   renderStreaming,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const stream = await renderStreaming(request, <ServerRoot />, options);
 

package/docs/zh/apis/app/runtime/ssr/renderString.mdx

@@ -12,9 +12,10 @@ title: renderString
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {
@@ -43,9 +44,10 @@ export type RenderString = (
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   // do something before render
   const body = await renderString(request, <ServerRoot />, options);
 

package/docs/zh/apis/app/runtime/ssr/requestHandler.mdx

@@ -12,9 +12,10 @@ title: createRequestHandler
 import {
   renderString,
   createRequestHandler,
+  type HandleRequest,
 } from '@modern-js/runtime/ssr/server';
 
-const handleRequest = async (request, ServerRoot, options) => {
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
   const body = await renderString(request, <ServerRoot />, options);
 
   return new Response(body, {

package/docs/zh/components/enable-bff-caution.mdx

@@ -1,4 +1,4 @@
 :::tip
-请先参考[基础用法](/guides/advanced-features/bff/function.html#启用-bff)中的"启用 BFF"部分，完成 BFF 功能的启用。
+请先参考 [基础用法](/guides/advanced-features/bff/function.html#启用-bff) 中的"启用 BFF"部分，完成 BFF 功能的启用。
 
 :::

package/docs/zh/configure/_meta.json

@@ -73,5 +73,6 @@
     "label": "experiments",
     "collapsed": true
   },
-  "app/builder-plugins"
+  "app/builder-plugins",
+  "app/split-chunks"
 ]

package/docs/zh/configure/app/output/dist-path.mdx

@@ -4,6 +4,10 @@ title: distPath
 
 # output.distPath
 
+import CommentTips from '@site-docs/components/output-distpath-warning';
+
+<CommentTips />
+
 - **类型：**
 
 ```ts

package/docs/zh/configure/app/runtime/router.mdx

@@ -4,15 +4,15 @@ title: router
 
 # router
 
-- **类型：** `boolean | Object`
-- **默认值：** `false`
+- **类型：** `Object`
+- **默认值：** `{}`
 
-该值在项目创建时被设置为 `true`，支持使用 Modern.js 默认提供的[约定式路由](/guides/concept/entries.html#约定式路由)进行路由管理。
-
-如果希望使用[自控式路由](/guides/concept/entries.html#自控式路由)，请移除该值，或将该值设置为 `false`。
+该配置项用于配置客户端路由，支持使用 Modern.js 默认提供的[约定式路由](/guides/concept/entries.html#约定式路由)进行路由管理。
 
 :::note
-`router` 的所有子配置都只会在使用约定式路由时生效。
+`router` 配置项**仅在使用约定式路由入口时生效**（即入口中存在 `routes/` 目录）。对于自控式路由入口或自定义入口，该配置不会生效。
+
+在多入口应用中，可以通过 `defineRuntimeConfig` 的函数形式为不同入口配置不同的路由行为，详见[运行时配置介绍](/configure/app/runtime/0-intro#多入口配置)。
 :::
 
 ## basename

package/docs/zh/configure/app/split-chunks.mdx

@@ -0,0 +1,17 @@
+# splitChunks
+
+- **类型：**
+
+```ts
+type SplitChunksConfig =
+  | (Rspack.OptimizationSplitChunksOptions & {
+      preset?: SplitChunksPreset;
+    })
+  | false;
+```
+
+`splitChunks` 用于配置 Rsbuild 的 chunk 拆分策略。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="splitChunks" />

package/docs/zh/guides/advanced-features/page-performance/optimize-bundle.mdx

@@ -99,18 +99,3 @@ export default {
 良好的拆包策略对于提升应用的加载性能是十分重要的，可以充分利用浏览器的缓存机制，减少请求数量，加快页面加载速度。
 
 在 Modern.js 中内置了[多种拆包策略](https://rsbuild.rs/zh/guide/optimization/split-chunk)，可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。
-
-比如将 node_modules 下的 `axios` 库拆分到 `axios.js` 中：
-
-```js
-export default {
-  performance: {
-    chunkSplit: {
-      strategy: 'split-by-experience',
-      forceSplitting: {
-        axios: /node_modules\/axios/,
-      },
-    },
-  },
-};
-```

package/docs/zh/guides/advanced-features/page-performance/react-compiler.mdx

@@ -30,20 +30,23 @@ npm install babel-plugin-react-compiler
 
 ```ts title="modern.config.ts"
 import { appTools, defineConfig } from '@modern-js/app-tools';
+import { pluginBabel } from '@rsbuild/plugin-babel';
 
 export default defineConfig({
-  tools: {
-    babel(_, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-react-compiler',
+  builderPlugins: [
+    pluginBabel({
+      babelLoaderOptions: (config, { addPlugins }) => {
+        addPlugins([
+          [
+            'babel-plugin-react-compiler',
           {
             target: '18', // 或 '17'，根据你使用的 React 版本
           },
-        ],
-      ]);
-    },
-  },
+          ],
+        ]);
+      },
+    });
+  ];
   plugins: [appTools()],
 });
 ```

package/docs/zh/guides/basic-features/render/streaming-ssr.mdx

@@ -235,14 +235,33 @@ function ErrorElement() {
 }
 ```
 
-## 为爬虫等待所有内容加载完毕
+## 控制是否等待全部内容再输出
 
-流式传输可以提高用户体验，因为当页面内容可用时，用户可以及时感知到它们。
+流式传输可以提高用户体验，因为当页面内容可用时，用户可以及时感知到它们。但在部分场景下（例如 SEO 爬虫、特定 AB 实验或合规页面）希望等所有内容完成后再一次性输出。
 
-然而，当一个爬虫访问该页面时，它可能需要先加载所有内容，直接输出整个 HTML，而不是渐进式地加载它。
+Modern.js 默认行为的判定优先级为：
 
 Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `user-agent`，以判断请求是否来自爬虫。
 
+1. 请求头 `x-should-stream-all`（中间件可写）。
+2. 环境变量 `MODERN_JS_STREAM_TO_STRING`（强制全量）。
+3. [isbot](https://www.npmjs.com/package/isbot) 检测 `user-agent`（爬虫全量）。
+4. 默认流式（先 shell 后内容）。
+
+你可以在自定义中间件里按请求动态写入标记，控制是否等待全部内容：
+
+```ts title="middleware 示例"
+export const middleware = async (ctx, next) => {
+  const ua = ctx.req.header('user-agent') || '';
+  const shouldWaitAll =
+    /Lighthouse|Googlebot/i.test(ua) || ctx.req.path === '/marketing';
+
+  // 写入布尔值字符串，true 表示使用 onAllReady，false 表示使用 onShellReady
+  ctx.req.headers.set('x-should-stream-all', String(shouldWaitAll));
+
+  await next();
+};
+```
 
 import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
 

package/docs/zh/guides/troubleshooting/builder.mdx

@@ -54,19 +54,7 @@ Inspect config succeed, open following files to view the content:
 该问题有两种解决方法：
 
 1. 避免将 CommonJS 模块加入到 Babel 编译中。
-2. 将 Babel 的 `sourceType` 配置项设置为 `unambiguous`，示例如下：
-
-```js
-export default {
-  tools: {
-    babel(config) {
-      config.sourceType = 'unambiguous';
-    },
-  },
-};
-```
-
-将 `sourceType` 设置为 `unambiguous` 可能会产生一些其他影响，请参考 [Babel 官方文档](https://babeljs.io/docs/en/options#sourcetype)。
+2. 将 Babel 的 `sourceType` 配置项设置为 `unambiguous`。将 `sourceType` 设置为 `unambiguous` 可能会产生一些其他影响，请参考 [Babel 官方文档](https://babeljs.io/docs/en/options#sourcetype)。
 
 ---
 
@@ -91,63 +79,8 @@ Error: ES Modules may not assign module.exports or exports.*, Use ESM export syn
 如果你修改 Babel 配置后出现此问题，建议检查是否有以下错误用法：
 
 1. 配置了一个不存在的 plugin 或 preset，可能是名称拼写错误，或是未正确安装。
-
-```ts
-// 错误示例
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      // 该插件名称错误，或者未安装
-      addPlugins('babel-plugin-not-exists');
-    },
-  },
-};
-```
-
 2. 是否配置了多个 babel-plugin-import，但是没有在数组的第三项声明每一个 babel-plugin-import 的名称。
 
-```ts
-// 错误示例
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd', libraryDirectory: 'es' },
-        ],
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
-        ],
-      ]);
-    },
-  },
-};
-```
-
-```ts
-// 正确示例
-export default {
-  tools: {
-    babel(config, { addPlugins }) {
-      addPlugins([
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd', libraryDirectory: 'es' },
-          'antd',
-        ],
-        [
-          'babel-plugin-import',
-          { libraryName: 'antd-mobile', libraryDirectory: 'es' },
-          'antd-mobile',
-        ],
-      ]);
-    },
-  },
-};
-```
-
 ---
 
 ### 从 lodash 中引用类型后出现编译报错？

package/docs/zh/guides/upgrade/tailwindcss.mdx

@@ -100,23 +100,26 @@ export default {
 2. 在 `modern.config.ts` 中配置 `babel-plugin-macros` 插件：
 
 ```ts title="modern.config.ts"
+import { pluginBabel } from '@rsbuild/plugin-babel';
+
 export default defineConfig({
-  plugins: [appTools()],
-  tools: {
-    babel: {
-      plugins: [
-        [
-          'babel-plugin-macros',
-          {
-            twin: {
-              preset: 'styled-components',
-              config: './tailwind.config.ts',
+  builderPlugins: [
+    pluginBabel({
+      babelLoaderOptions: {
+        plugins: [
+          [
+            'babel-plugin-macros',
+            {
+              twin: {
+                preset: 'styled-components',
+                config: './tailwind.config.js',
+              },
             },
-          },
+          ],
         ],
-      ],
-    },
-  },
+      },
+    }),
+  ],
 });
 ```
 

package/docs/zh/plugin/cli-plugins/api.mdx

@@ -47,7 +47,7 @@ export default myCliPlugin;
 | `isProd`               | `boolean`           | 是否为生产模式                                     | -                           |
 | `appDirectory`         | `string`            | 项目根目录的绝对路径                               | -                           |
 | `srcDirectory`         | `string`            | 项目源码目录的绝对路径                             | -                           |
-| `distDirectory`        | `string`            | 项目产物输出目录的绝对路径                         | `modifyResolvedConfig` 之后 |
+| `distDirectory`        | `string`            | 项目产物输出目录的绝对路径                         | `onPrepare`（及之后）       |
 | `sharedDirectory`      | `string`            | 公共模块目录的绝对路径                             | -                           |
 | `nodeModulesDirectory` | `string`            | `node_modules` 目录的绝对路径                      | -                           |
 | `ip`                   | `string`            | 当前机器的 IPv4 地址                               | -                           |
@@ -102,18 +102,13 @@ api.onPrepare(() => {
 获取经过 Modern.js 内部处理和插件修改后的最终配置（归一化配置）。
 
 - **返回值：** 归一化后的配置对象。
-- **何时可用：** 必须在 `modifyResolvedConfig` 钩子之后使用。
+- **何时可用：** 必须在 `onPrepare`（及之后的 hook，例如 `onBeforeBuild`）中使用。
 - **示例：**
 
 ```typescript
-api.modifyResolvedConfig(resolvedConfig => {
-  // ... 修改配置 ...
-  return resolvedConfig;
-});
-
-api.onBeforeBuild(() => {
+api.onPrepare(() => {
   const finalConfig = api.getNormalizedConfig();
-  console.log('最终构建配置：', finalConfig);
+  console.log('最终配置：', finalConfig);
 });
 ```
 

package/docs/zh/plugin/introduction.mdx

@@ -46,7 +46,7 @@ CLI 插件用于在应用执行 `modern` 命令时提供额外功能，例如添
 CLI 插件可通过 `modern.config.ts` 中的 `plugins` 字段进行配置。
 
 ```ts title="modern.config.ts"
-// an example for bff
+// bff 的示例
 import { appTools, defineConfig } from '@modern-js/app-tools';
 import { bffPlugin } from '@modern-js/plugin-bff';
 

package/package.json

@@ -15,20 +15,21 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.2",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.12.2",
-    "@modern-js/sandpack-react": "3.0.0-alpha.1"
+    "@modern-js/sandpack-react": "3.0.0-alpha.2"
   },
   "devDependencies": {
-    "@rsbuild/plugin-sass": "1.4.0",
-    "@shikijs/transformers": "^3.20.0",
-    "@rspress/shared": "2.0.0-rc.0",
+    "@rsbuild/plugin-sass": "1.5.0",
+    "@rspress/core": "2.0.0-rc.0",
     "@rspress/plugin-llms": "2.0.0-rc.0",
+    "@rspress/shared": "2.0.0-rc.0",
+    "@shikijs/transformers": "^3.21.0",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^20",
     "classnames": "^2.5.1",
@@ -36,7 +37,6 @@
     "fs-extra": "^10.1.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
-    "@rspress/core": "2.0.0-rc.0",
     "ts-node": "^10.9.2",
     "typescript": "^5"
   },

package/src/components/Footer/index.tsx

@@ -38,7 +38,7 @@ export default function Footer() {
         },
         {
           label: t('advancedFeatures'),
-          to: useUrl('/guides/advanced-features/rspack-start'),
+          to: useUrl('/guides/advanced-features/bff'),
         },
       ],
     },

package/src/components/RsbuildLink/index.tsx

@@ -3,7 +3,7 @@ import React from 'react';
 
 const RsbuildLink = ({ configName }: { configName: string }) => {
   const lang = useLang();
-  const href = `https://rsbuild.rs/${lang === 'zh' ? 'zh/' : ''}config/${configName
+  const href = `https://v2.rsbuild.rs/${lang === 'zh' ? 'zh/' : ''}config/${configName
     .split('.')
     .join('/')
     .replace(/([a-z])([A-Z])/g, '$1-$2')

package/docs/en/components/esbuild.mdx

@@ -1,3 +0,0 @@
-[esbuild](https://esbuild.github.io/) is a front-end build tool based on Golang. It has the functions of bundling, compiling and minimizing JavaScript code. Compared with traditional tools, the performance is significantly improved. When minimizing code, esbuild has dozens of times better performance.
-
-Modern.js provides esbuild plugin that allow you to use esbuild instead of babel-loader, ts-loader for transformation and minification process. When you enable esbuild in a large project, **it can greatly reduce the time required for code compilation and compression, while effectively avoiding OOM (heap out of memory) problems**.

package/docs/en/guides/advanced-features/rspack-start.mdx

@@ -1,137 +0,0 @@
----
-sidebar_position: 1
----
-
-# Using Rspack
-
-import Rspack from '@site-docs-en/components/rspackTip.mdx';
-
-<Rspack />
-
-**Modern.js provides out-of-the-box Rspack support**, so you can switch between the stable webpack and the faster Rspack.
-
-This document will show you how to enable Rspack build mode in Modern.js.
-
-## Initializing an Rspack project
-
-The Modern.js new project has enabled Rspack by default. Just execute [Initialize Project](/guides/get-started/quick-start.html#initialize) to create an Rspack project:
-
-import InitRspackApp from '@site-docs-en/components/init-rspack-app';
-
-<InitRspackApp />
-
-After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).
-
-import RspackPrecautions from '@site-docs-en/components/rspackPrecautions.mdx';
-
-<RspackPrecautions />
-
-## Migrating configuration
-
-In Modern.js, the [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain) configurations take effect in Rspack mode. If you were previously using webpack mode, after turning on the Rspack build, you can modify it to [tools.rspack](/configure/app/tools/rspack) and [tools.bundlerChain](/configure/app/tools/bundler-chain).
-
-```diff
-export default {
-  tools: {
--   webpack: (config, { env }) => {
-+   rspack: (config, { env }) => {
-      if (env === 'development') {
-        config.devtool = 'cheap-module-eval-source-map';
-      }
-      return config;
-    },
--   webpackChain: (chain, { env }) => {
-+   bundlerChain: (chain, { env }) => {
-      if (env === 'development') {
-        chain.devtool('cheap-module-eval-source-map');
-      }
-    },
-  },
-};
-```
-
-## Modify transpile configuration
-
-Modern.js uses Rspack [builtin:swc-loader](https://rspack.rs/guide/features/builtin-swc-loader) for code translation in Rspack mode.
-
-Modern.js has provided a more convenient configuration for the common configuration of `builtin:swc-loader`, such as: configuring the component library to import it on demand through [source.transformImport](/configure/app/source/transform-import).
-
-If you have custom configuration requirements for `builtin:swc-loader`, you can set the options of builtin:swc-loader through [tools.swc](/configure/app/tools/swc):
-
-```ts
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  tools: {
-    swc: {
-      jsc: {
-        externalHelpers: false,
-      },
-    },
-  },
-});
-```
-
-:::tip
-When Rspack build is enabled, `babel-loader` is not enabled by default. If you need to add some babel plugins, you can configure it through [babel plugin](https://rsbuild.rs/plugins/list/plugin-babel#babel-plugin). This will generate additional compilation overhead and slow down the Rspack build speed to a certain extent.
-:::
-
-## The relationship between Rspack and Modern.js versions
-
-Usually, the latest version of Rspack will be integrated into Modern.js. You can update the Modern.js-related dependencies and built-in Rspack to the latest version by using `npx modern upgrade` in your project.
-
-However, Modern.js uses a locked version dependency method (non-automatic upgrade) for Rspack. Due to differences in release cycles, the version of Rspack integrated into Modern.js may be behind the latest version of Rspack.
-
-When Rspack is enabled for building through dev / build, the current version of Rspack used in the framework will be printed automatically when [debugging mode](https://rsbuild.rs/guide/debug/debug-mode) is turned on:
-
-![rspack_version_log](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/20240110-155444.png)
-
-### Override the Built-in Rspack Version
-
-You can override Rspack to a specific version using the capbilities provided by package managers such as pnpm, yarn, npm.
-
-For example, if you are using pnpm, you can override the Rspack version with `overrides`. Assume that the version of Rspack needs to be specified as 0.7.5:
-
-```json title=package.json
-{
-  "pnpm": {
-    "overrides": {
-      "@rspack/binding": "0.7.5",
-      "@rspack/core": "0.7.5",
-      "@rspack/plugin-react-refresh": "0.7.5"
-    }
-  }
-}
-```
-
-If you need to use the nightly/canary version of Rspack, the package name of the nightly/canary version of Rspack will be released after adding the `-canary` suffix, and needs to be modified to:
-
-```json title=package.json
-{
-  "pnpm": {
-    "overrides": {
-      "@rspack/binding": "npm:@rspack/binding-canary@nightly",
-      "@rspack/core": "npm:@rspack/core-canary@nightly",
-      "@rspack/plugin-react-refresh": "npm:@rspack/plugin-react-refresh-canary@nightly"
-    },
-    "peerDependencyRules": {
-      "allowAny": ["@rspack/*"]
-    }
-  }
-}
-```
-
-Rspack provides [install-rspack](https://github.com/rspack-contrib/install-rspack) tooling to quickly override versions:
-
-```sh
-npx install-rspack --version nightly # nightly npm tag
-npx install-rspack --version 0.7.5-canary-d614005-20240625082730 # A specific canary version
-```
-
-:::tip What is Rspack Nightly Version
-The Rspack nightly build fully replicates the full release build for catching errors early.
-Usually it is available and any errors that arise will fixed promptly.
-However, if there are any break changes that require modern.js to modify the code, we recommend to wait for the next version of modern.js.
-:::
-
-More examples of using package managers, please refer to: [Lock nested dependency](/guides/get-started/upgrade.html#lock-nested-dependency).

package/docs/zh/components/esbuild.mdx

@@ -1,3 +0,0 @@
-[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，esbuild 在性能上有数十倍的提升。
-
-Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 等库进行代码编译和压缩。在大型工程中启用 esbuild 后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。