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

package/docs/zh/configure/app/output/ssg.mdx

@@ -11,10 +11,19 @@ title: ssg
 
 :::tip 开启 SSG 功能
 此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/basic-features/render/ssg) 文档了解如何开启 SSG 功能及使用场景。
+
 :::
 
 :::info 前置阅读
-SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/guides/basic-features/routes)。
+SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/guides/basic-features/routes/routes)。
+
+:::
+
+:::info
+- 单入口建议使用 `output.ssg`。
+- 多入口建议优先使用 `output.ssgByEntries`。
+- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+
 :::
 
 ## Boolean 类型
@@ -29,36 +38,6 @@ export default defineConfig({
 });
 ```
 
-`output.ssg` 也可以按照入口配置，配置生效的规则同样由入口路由方式决定。
-
-例如以下目录结构，分别存在约定式路由入口 `entryA` 和自控式路由入口 `entryB`：
-
-```bash
-.
-└── src
-    ├── entryA
-    │   └── routes
-    └── entryB
-        └── App.tsx
-```
-
-你可以指定 `entryA` 和 `entryB` 的不同 SSG 配置：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      entryA: true,
-      entryB: false,
-    },
-  },
-});
-```
-
-:::info
-更多关于**约定式路由**和**自控式路由**在开启 SSG 后的默认行为，请阅读 [静态站点生成](/guides/basic-features/render/ssg) 。
-:::
-
 ## Object 类型
 
 当值类型为 `Object` 时，可以配置如下属性。
@@ -70,12 +49,10 @@ type SSGRouteOptions =
   | string
   | {
       url: string;
-      params?: Record<string, any>[];
       headers?: Record<string, any>;
     };
 
 type SSGOptions = {
-  preventDefault?: string[];
   headers?: Record<string, any>;
   routes?: SSGRouteOptions[];
 };
@@ -85,9 +62,9 @@ type SSGOptions = {
 
 下面的示例配置中，SSG 会渲染 `/`、`/about` 和 `/user/:id` 三条路由对应的页面。
 
-对于 `/user/:id` 路由，`cookies` 添加到请求头中，同时会将 `params` 中的 `id` 替换为 `modernjs`。
+对于 `/user/:id` 路由，会在请求头中添加 `cookies`，并指定具体的路径。
 
-```ts title="modern.config.ts"
+```ts title="modern.config.ts（单入口）"
 export default defineConfig({
   output: {
     ssg: {
@@ -95,22 +72,13 @@ export default defineConfig({
         '/',
         '/about',
         {
-          url: '/user/:id',
+          url: '/user/modernjs',
           headers: {
             cookies: 'name=modernjs',
           },
-          params: [
-            {
-              id: 'modernjs',
-            },
-          ],
         },
       ],
     },
   },
 });
 ```
-
-:::note
-多入口的情况和单入口的配置方式一致，这里不再额外介绍。
-:::

package/docs/zh/configure/app/output/ssgByEntries.mdx

@@ -0,0 +1,94 @@
+---
+title: ssgByEntries
+---
+
+# output.ssgByEntries
+
+- **类型：** `Record<string, boolean | object>`
+- **默认值：** `undefined`
+
+在多入口应用中，为每个入口分别配置 SSG。
+
+:::info
+- 单入口建议使用 `output.ssg`。
+- 多入口建议优先使用 `output.ssgByEntries`。
+- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+
+:::
+
+
+## 配置类型
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+
+// ssgByEntries 类型
+type SSGMultiEntryOptions = Record<string, boolean | SSGOptions>;
+```
+
+## 示例
+
+### 按入口启用/禁用 SSG
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: true,
+      admin: false,
+    },
+  },
+});
+```
+
+### 按入口配置具体路由
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: {
+        routes: ['/', '/dashboard'],
+      },
+    },
+  },
+});
+```
+
+### 配置入口或路由请求头
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        headers: {
+          'x-tt-env': 'ppe_modernjs',
+        },
+        routes: [
+          '/',
+          {
+            url: '/about',
+            headers: {
+              from: 'modern-website',
+            },
+          },
+        ],
+      },
+    },
+  },
+});
+```

package/docs/zh/configure/app/output/temp-dir.mdx

@@ -7,7 +7,7 @@ title: tempDir
 - **类型：** `string`
 - **默认值：** `''`
 
-项目开发或构建时，Modern.js 会生成真实的 Webpack 入口和 HTML 模板，并放在临时目录下。
+项目开发或构建时，Modern.js 会生成真实的 Rspack 入口和 HTML 模板，并放在临时目录下。
 
 如果希望由多个配置同时启动某项目，可以通过该配置，将文件生成到不同的临时目录下，避免相互干扰。配置可以是相对路径或绝对路径，但应避免项目外的路径。
 
@@ -17,6 +17,6 @@ title: tempDir
 export default {
   output: {
     tempDir: path.join('node_modules', '.temp-dir'),
-  }
-}
+  },
+};
 ```

package/docs/zh/configure/app/performance/build-cache.mdx

@@ -19,7 +19,7 @@ type BuildCacheConfig =
       cacheDigest?: Array<string | undefined>;
       /**
        * 一个包含构建依赖的文件数组。
-       * Rspack / webpack 将使用其中每个文件的哈希值来判断持久化缓存是否失效。
+       * Rspack 将使用其中每个文件的哈希值来判断持久化缓存是否失效。
        */
       buildDependencies?: string[];
     }
@@ -38,10 +38,6 @@ export default {
 };
 ```
 
-::: warning
-从 `v2.69.0` 版本开始，Modern.js rspack 构建将默认开启 buildCache，之前版本需要手动配置开启。
-:::
-
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="performance.buildCache" />

package/docs/zh/configure/app/performance/profile.mdx

@@ -7,7 +7,7 @@ title: profile
 - **类型：** `boolean`
 - **默认值：** `false`
 
-是否捕获每个模块的耗时信息，对应 Rspack 的 [profile](https://webpack.js.org/configuration/other-options/#profile) 配置。
+是否捕获每个模块的耗时信息，对应 Rspack 的 [profile](https://rspack.rs/zh/config/other-options#profile) 配置。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/plugins.mdx

@@ -10,8 +10,7 @@
 该选项**用于配置框架 CLI 插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
 
 - 配置 Rsbuild 插件，请使用 [builderPlugins](/configure/app/builder-plugins) 配置项。
-- 配置 Rspack 或 webpack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
-- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+- 配置 Rspack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
 - 配置框架 Runtime 插件，请使用 [runtime 配置文件 plugins](/configure/app/runtime/plugins) 配置项。
 
 ## 示例

package/docs/zh/configure/app/resolve/alias-strategy.mdx

@@ -0,0 +1,14 @@
+---
+title: aliasStrategy
+---
+
+# resolve.aliasStrategy
+
+- **类型:** `'prefer-tsconfig' | 'prefer-alias'`
+- **默认值:** `'prefer-tsconfig'`
+
+设置路径别名解析的策略，用于控制 `tsconfig.json` 中的 paths 选项与 Rsbuild 的 [resolve.alias](https://rsbuild.rs/config/resolve/alias) 选项之间的优先级关系。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.aliasStrategy" />

package/docs/zh/configure/app/resolve/alias.mdx

@@ -0,0 +1,13 @@
+---
+title: alias
+---
+
+# resolve.alias
+
+- **类型:** `string[]`
+
+设置模块路径的别名，用于简化导入路径或重定向模块引用。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.alias" />

package/docs/zh/configure/app/resolve/condition-names.mdx

@@ -0,0 +1,18 @@
+---
+title: conditionNames
+---
+
+# resolve.conditionNames
+
+- **类型:** `string[]`
+- **默认值:** 与 Rsbuild 的 `resolve.conditionNames` 一致
+
+指定用于匹配包 [exports](https://nodejs.org/api/packages.html#packages_exports) 字段 入口点的 condition names（条件名称）。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.extensions" />
+
+:::warning
+SSR 应用请勿启用此配置项，否则会导致 SSR 渲染失败。
+:::

package/docs/zh/configure/app/resolve/dedupe.mdx

@@ -0,0 +1,14 @@
+---
+title: dedupe
+---
+
+# resolve.dedupe
+
+- **类型:** `string[]`
+
+强制 Rsbuild 从项目根目录解析指定的包，这可以用于移除重复包和减少包大小。对应 Rsbuild 的 [resolve.dedupe](https://rsbuild.rs/config/resolve/dedupe) 配置。
+
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.dedupe" />

package/docs/zh/configure/app/resolve/extensions.mdx

@@ -0,0 +1,18 @@
+---
+title: extensions
+---
+
+# resolve.extensions
+
+- **类型:** `string[]`
+- **默认值:** `['.ts', '.tsx', '.mjs', '.js', '.jsx', '.json']`
+
+自动添加导入文件的扩展名。这意味着你可以导入文件，而不需要显式地写它们的扩展名。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.extensions" />
+
+:::warning
+SSR 应用请勿启用此配置项，否则会导致 SSR 渲染失败。
+:::

package/docs/zh/configure/app/runtime/0-intro.mdx

@@ -2,12 +2,6 @@
 
 Modern.js 的运行时（Runtime）配置需集中在 `src/modern.runtime.ts` 文件中声明。
 
-:::warning
-
-使用 `src/modern.runtime.ts` 配置方式需要 Modern.js 版本 **MAJOR_VERSION.66.0** 或更高版本。
-
-:::
-
 :::info
 如果项目中还没有此文件，请执行以下命令创建：
 
@@ -26,9 +20,6 @@ export default defineRuntimeConfig({
   router: {
     // 路由配置
   },
-  state: {
-    // 状态管理配置
-  },
   // 其他运行时模块...
 });
 ```
@@ -46,16 +37,13 @@ export default defineRuntimeConfig(entryName => {
       router: {
         // "main" 入口的路由配置
       },
-      state: {
-        // "main" 入口的状态管理配置
-      },
     };
   }
 
   // 其他入口的配置
   return {
-    masterApp: {
-      // 微前端配置示例
+    router: {
+      // 其他入口的路由配置
     },
   };
 });
@@ -65,45 +53,6 @@ export default defineRuntimeConfig(entryName => {
 使用 `src/modern.runtime.ts` 配置方式不支持导出异步函数，这与 Modern.js 的渲染方式有关。如果需要添加异步逻辑，请使用 **[Runtime 插件 (Runtime Plugin)](/plugin/introduction.html#runtime-插件)**。
 :::
 
-
-
 import RuntimeCliConfig from '@site-docs/components/runtime-cli-config';
 
 <RuntimeCliConfig />
-
-## 配置方式演进
-
-在 MAJOR_VERSION.66.0 之前，运行时配置分散在多个位置：
-
-1. `modern.config.ts` 中的 `runtime` 和 `runtimeByEntries` 字段
-2. 各入口的 `App.config` 或 `layout` 文件导出的 `config` 函数
-
-为提升可维护性，Modern.js 引入了统一的 `src/modern.runtime.ts` 配置入口。
-
-### 旧配置方式（兼容但不推荐）
-
-```ts
-// modern.config.ts
-export default {
-  runtime: {
-    /* ... */
-  },
-  runtimeByEntries: {
-    /* ... */
-  },
-};
-
-// App.config
-App.config = {
-  /* ... */
-};
-
-// layout 文件
-export const config = () => {
-  /* 动态配置逻辑 */
-};
-```
-
-### 迁移建议
-
-强烈建议将所有运行时配置迁移至 `src/modern.runtime.ts`。虽然旧配置方式目前仍兼容，但计划在未来版本中逐步废弃。统一配置入口可避免配置分散，显著提高项目可维护性。

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

@@ -4,10 +4,6 @@ title: router
 
 # router
 
-import RouterLegacyTip from "@site-docs/components/router-legacy-tip"
-
-<RouterLegacyTip />
-
 - **类型：** `boolean | Object`
 - **默认值：** `false`
 

package/docs/zh/configure/app/security/check-syntax.mdx

@@ -57,7 +57,7 @@ error   [Syntax Checker] Find some syntax errors after production build:
 
 :::tip
 目前语法检测是基于 AST parser 来实现的，每次检测时，只能找出文件中的第一个不兼容语法。如果一个文件中存在多个不兼容语法，你需要修复已发现的语法，并重新执行检测。
-如果日志中没有显示对应的源码位置，可以尝试将 **output.disableMinimize** 设置为 true 后再重新构建。
+如果日志中没有显示对应的源码位置，可以尝试将 **output.minify** 设置为 false 后再重新构建。
 :::
 
 ### 解决方法

package/docs/zh/configure/app/security/sri.mdx

@@ -10,7 +10,6 @@ title: sri
 type SriOptions = {
   hashFuncNames?: [string, ...string[]];
   enabled?: 'auto' | true | false;
-  hashLoading?: 'eager' | 'lazy'; // only support webpack
 };
 ```
 

package/docs/zh/configure/app/server/port.mdx

@@ -7,7 +7,7 @@ title: port
 - **类型：** `number`
 - **默认值：** `8080`
 
-Modern.js 在执行 `dev`, `start` 和 `serve` 命令时，会以 `8080` 为默认端口启动，并会在端口被占用时自动递增端口号。你可以通过该配置来修改 Server 启动的端口号：
+Modern.js 在执行 `dev` 和 `serve` 命令时，会以 `8080` 为默认端口启动，并会在端口被占用时自动递增端口号。你可以通过该配置来修改 Server 启动的端口号：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -17,26 +17,7 @@ export default defineConfig({
 });
 ```
 
-### 与 dev.port 的区别
-
-大多数情况下，我们推荐使用 `server.port` 而不是 `dev.port` 来设置端口号，他们之间的区别如下：
-
-- `dev.port` 仅在开发环境下生效，`server.port` 在开发环境和生产环境下均能生效。
-- 在开发环境下，`dev.port` 的优先级高于 `server.port`。
-
-当你同时设置 `dev.port` 和 `server.port` 时，`dev.port` 会在开发环境下生效，`server.port` 会在生产环境下生效。比如以下例子，在开发环境下监听的端口号为 `3001`，在生产环境下监听的端口号为 `3002`。
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    port: 3001,
-  },
-  server: {
-    port: 3002,
-  },
-});
-```
-
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="server.port" />
+```

package/docs/zh/configure/app/server/rsc.mdx

@@ -0,0 +1,30 @@
+---
+title: rsc
+---
+
+# server.rsc
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+启用 React Server Components (RSC) 配置。
+
+当设置为 `true` 时，启用 Modern.js 的 React Server Components 支持。这允许组件在服务端渲染，提供更好的性能和开发体验。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  server: {
+    rsc: true,
+  },
+});
+```
+
+:::tip 前置条件
+在启用 RSC 之前，请确保：
+1. React 和 React DOM 已升级到 19 版本（建议 19.2.3 以上版本）
+2. 已安装 `react-server-dom-webpack` 依赖
+
+:::
+
+有关使用 RSC 的更多信息，请参阅 [React Server Components 指南](/guides/basic-features/render/rsc)。
+

package/docs/zh/configure/app/server/ssr.mdx

@@ -27,11 +27,10 @@ export default defineConfig({
 
 | 属性              | 类型                                                               | 默认值                                   | 描述                                                                     |
 | ---------------- | ------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
-| mode             | `string`                                  | `string`          | 默认为使用 `renderToString` 渲染。配置为 `stream` 开启流式渲染       |
+| mode             | `string`                                  | `stream`          | 默认为使用流式渲染。配置为 `string` 使用 `renderToString` 渲染       |
 | forceCSR         | `boolean`                                 | `false`           | 默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 或添加请求头 `x-modern-ssr-fallback` 即可强制 CSR |
-| disablePrerender | `boolean`                                 | `fasle`           | 为了兼容旧数据请求方式 - `useLoader`, 默认情况下 Modern.js 会对组件进行一次预渲染即有两次渲染 |
 | unsafeHeaders    | `string[]`                                | `[]`              | 为了安全考虑，Modern.js 不会往 SSR_DATA 添加过多的内容。开发者可以通过该配置，对需要注入的 headers 进行配置       |
-| loaderFailureMode| `clientRender \| errorBoundary`           | `errorBoundary` | 当 [data loader](/guides/basic-features/data/data-fetch.html#data-loader推荐) 中出错时，默认会渲染路由 [`Error`](/guides/basic-features/routes.html#错误处理) 组件，配置为 `'clientRender'` 时，有一个 data loader 抛错，就降级到客户端渲染，可以与 [Client Loader](/guides/basic-features/data/data-fetch.html#client-loader) 配合使用 |
+| loaderFailureMode| `clientRender \| errorBoundary`           | `errorBoundary` | 当 [data loader](/guides/basic-features/data/data-fetch.html#data-loader推荐) 中出错时，默认会渲染路由 [`Error`](/guides/basic-features/routes/routes#错误处理) 组件，配置为 `'clientRender'` 时，有一个 data loader 抛错，就降级到客户端渲染，可以与 [Client Loader](/guides/basic-features/data/data-fetch.html#client-loader) 配合使用 |
 
 
 ```ts title="modern.config.ts"
@@ -40,7 +39,6 @@ export default defineConfig({
     ssr: {
       forceCSR: true,
       mode: 'stream',
-      disablePrerender: true,
       unsafeHeaders: ['User-Agent'],
       scriptLoading: 'async',
     },
@@ -58,17 +56,29 @@ export default defineConfig({
 
 3. SSR 服务压力过大，需要部分流量直接降级为 CSR，避免服务宕机。
 
-在项目中配置 `server.ssr.forceCSR` 为 `true` 后，我们可以通过请求的查询字符串，或是请求头来控制这一行为。
+在项目中配置 `server.ssr.forceCSR` 为 `true` 后，我们可以通过请求的查询字符串、context，或是请求头来控制这一行为。
 
 例如在自定义 Web Server 的中间件中，检测到流量大于某一阈值时，主动降级：
 
-```ts title="server/index.ts"
-export const middleware = (ctx, next) => {
-  const { req, res } = ctx;
+```ts title="server/modern.server.ts"
+import {
+  defineServerConfig,
+  type MiddlewareHandler,
+} from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
   if (condition) {
-    req.headers['x-modern-ssr-fallback'] = '1';
+    c.set('forceCSR', '1');
   }
-
-  next();
+  await next();
 };
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-middleware',
+      handler,
+    },
+  ],
+});
 ```

package/docs/zh/configure/app/source/alias.mdx

@@ -12,7 +12,7 @@ type Alias = Record<string, string | false | (string | false)[]> | Function;
 
 - **默认值:** `undefined`
 
-设置文件引用的别名，对应 Rspack 的 [resolve.alias](https://webpack.js.org/configuration/resolve/#resolvealias) 配置。
+设置文件引用的别名，对应 Rspack 的 [resolve.alias](https://rspack.rs/config/resolve#resolvealias) 配置。
 
 :::tip
 对于 TypeScript 项目，你只需要在 `tsconfig.json` 中配置 [compilerOptions.paths](https://www.typescriptlang.org/tsconfig#paths) 即可，Rsbuild 会自动识别它，不需要额外配置 `source.alias` 字段，详见 [「路径别名」](https://modernjs.dev/guides/basic-features/alias.html)。

package/docs/zh/configure/app/source/decorators.mdx

@@ -20,8 +20,8 @@ const defaultDecorators = {
 };
 ```
 
-用于配置装饰器语法。
+:::warning
+该配置项的使用方式与 Rsbuild 一致，但默认值不同。详细信息请参考 [Rsbuild - source.decorators](https://rsbuild.rs/zh/config/source/decorators)。
+:::
 
-import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
-
-<RsbuildConfig configName="source.decorators" />
+我们发现大部分的项目仍使用 `legacy` 版本的装饰器语法，因此默认值为 `legacy`。

package/docs/zh/configure/app/source/enable-async-entry.mdx

@@ -7,7 +7,7 @@ title: enableAsyncEntry
 - **类型：** `boolean`
 - **默认值：** `false`
 
-该选项用于 webpack 模块联邦（Module Federation）场景。
+该选项用于 Rspack 模块联邦（Module Federation）场景。
 
 开启此选项后，Modern.js 会通过 dynamic import 来包裹自动生成的入口文件（Asynchronous Boundaries），使页面代码可以消费模块联邦生成的远程模块。
 

package/docs/zh/configure/app/source/entries.mdx

@@ -13,7 +13,6 @@ type Entries = Record<
   | {
       entry: string;
       disableMount?: boolean;
-      customBootstrap?: string;
     }
 >;
 ```
@@ -84,7 +83,6 @@ export default defineConfig({
 
 - `entry`：`string`，入口文件路径。
 - `disableMount`：`boolean = false`，关闭 Modern.js 自动生成入口代码的行为。
-- `customBootstrap`： `string = ''`，指定[自定义 Bootstrap](/guides/concept/entries#自定义-bootstrap) 的文件路径。
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';