@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/zh/components/enable-ssg.mdx

@@ -0,0 +1,47 @@
+要在 Modern.js 项目中启用 SSG 功能，请按照以下步骤修改代码：
+
+1. 安装 SSG 插件依赖
+
+如果项目尚未安装 SSG 插件，请先安装：
+
+```bash
+pnpm add @modern-js/plugin-ssg
+```
+
+:::tip 版本一致性
+请确保 `@modern-js/plugin-ssg` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
+
+请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/plugin-ssg`：
+
+```bash
+# 查看当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/plugin-ssg
+pnpm add @modern-js/plugin-ssg@<版本号>
+```
+
+:::
+
+2. 配置 modern.config.ts
+
+在 `modern.config.[tj]s` 文件中导入并添加 SSG 插件，同时配置 `output.ssg`：
+
+```ts title="modern.config.ts"
+import { defineConfig, appTools } from '@modern-js/app-tools';
+import { ssgPlugin } from '@modern-js/plugin-ssg';
+
+export default defineConfig({
+  plugins: [appTools(), ssgPlugin()],
+  output: {
+    ssg: true,
+  },
+});
+```
+
+:::info 适用范围
+
+- 单入口请使用 `output.ssg`。
+- 多入口请使用 `output.ssgByEntries`。
+- 当仅设置 `output.ssg: true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+  :::

package/docs/zh/components/entry-scan-logic.mdx

@@ -0,0 +1,7 @@
+:::tip 入口扫描逻辑
+- 如果 `src/` 本身满足入口条件 → 单入口应用
+- 如果 `src/` 不满足条件 → 扫描 `src/` 下的子目录 → 多入口应用
+- 单入口应用中，默认入口名为 `index`
+
+:::
+

package/docs/zh/components/init-app.mdx

@@ -1,38 +1,60 @@
-`@modern-js/create` 会提供一个可交互的问答界面，根据结果初始化项目，按照默认的选择进行初始化：
+Modern.js 提供了 `@modern-js/create` 工具来创建项目，不需要全局安装，直接使用 `npx` 按需运行即可。
+
+你可以在已有的空目录来创建项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create@latest
+```
+
+也可以直接用新目录创建项目：
 
 ```bash
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
+npx @modern-js/create@latest myapp
 ```
 
-在生成项目后，Modern.js 会自动安装依赖、创建 git 仓库。
+`@modern-js/create` 会直接创建应用，不再提供问答界面：
 
 ```bash
-[INFO] 依赖自动安装成功
-[INFO] git 仓库初始化成功
-[INFO] 创建成功！
-可在新项目的目录下运行以下命令：
-pnpm run dev          # 启动开发服务器
-pnpm run build        # 构建生产环境产物
-pnpm run serve        # 启动生产环境服务
-pnpm run lint         # 运行 ESLint 并自动修复问题
-pnpm run new          # 启用可选功能或创建项目要素
+🚀 欢迎使用 Modern.js
+
+📦 正在创建项目 "myapp"...
+
+✨ 项目创建成功！🎉
+
+📋 接下来你可以执行以下命令：
+
+📁 进入项目目录：
+
+  cd myapp
+
+🔧 初始化 Git 仓库：
+
+  git init
+
+📥 安装项目依赖：
+
+  pnpm install
+
+⚡ 启动开发服务器：
+
+  pnpm start
 ```
 
 现在，项目结构如下：
 
 ```
 .
-├── node_modules
+├── biome.json
+├── modern.config.ts
+├── package.json
+├── README.md
 ├── src
 │   ├── modern-app-env.d.ts
+│   ├── modern.runtime.ts
 │   └── routes
 │       ├── index.css
 │       ├── layout.tsx
 │       └── page.tsx
-├── modern.config.ts
-├── package.json
-├── pnpm-lock.yaml
-├── README.md
 └── tsconfig.json
 ```

package/docs/zh/components/international/install-command.mdx

@@ -0,0 +1,8 @@
+```bash
+pnpm add @modern-js/plugin-i18n i18next react-i18next
+```
+
+:::info
+`i18next` 和 `react-i18next` 是 peer dependencies，需要手动安装。
+
+:::

package/docs/zh/components/international/introduce.mdx

@@ -0,0 +1,2 @@
+`@modern-js/plugin-i18n` 是 Modern.js 的国际化插件，基于
+[i18next](https://www.i18next.com/) 和 [react-i18next](https://react.i18next.com/) 构建，为 Modern.js 应用提供完整的国际化解决方案。

package/docs/zh/components/module-federation.mdx

@@ -1,7 +1,7 @@
-模块联邦（Module Federation，简称 MF）是 Webpack 的一个特性。它允许 JavaScript 应用从另一个应用动态加载代码，并在此过程中共享依赖关系。如果使用联邦模块的应用缺少联邦代码所需的依赖项，Webpack 将从该联邦的构建源下载缺失的依赖项。
+模块联邦（Module Federation，简称 MF）是一种让多个 JavaScript 应用可以共享代码和资源的技术方案。它类似于服务端的微服务架构，允许你将大型应用拆分成多个独立的小应用，这些小应用可以独立开发、测试和部署，同时还能在运行时动态加载其他应用的模块。
 
-这使得可以创建微前端风格的应用程序，多个系统可以共享代码，并在不需要重新构建整个应用程序的情况下进行动态更新。
+使用模块联邦可以解决多个前端应用之间代码重复的问题。传统方式下，如果多个应用需要使用相同的组件或工具函数，需要在每个应用中重复安装这些代码，导致代码重复、维护成本高、应用体积变大。使用模块联邦后，你可以将公共代码放在一个应用中，其他应用按需动态加载，实现代码共享，减少重复。
 
-Modern.js 提供了一个 Module Federation 的示例项目，请参考 [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs)。
+Module Federation 2.0 支持 [Rspack](https://rspack.rs/) 构建工具，并提供了动态类型提示、Manifest、Federation Runtime、运行时插件系统和 Chrome Devtools 等增强功能，提供更好的开发体验和调试能力。你可以访问 [Module Federation 官方文档](https://module-federation.io/zh/index.html) 了解更多信息。
 
-你也可以阅读 [webpack Module Federation 文档](https://webpack.docschina.org/concepts/module-federation/) 来了解更多概念。
+Modern.js 提供了一个 Module Federation 的示例项目，请参考 [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs)。

package/docs/zh/components/nodeVersion.mdx

@@ -1,4 +1,4 @@
-在开始使用前，你需要安装 [Node.js](https://nodejs.org/)，并保证 Node.js 版本不低于 18.20.8，**我们推荐使用 Node.js 22 的 LTS 版本**。
+在开始使用前，你需要安装 [Node.js](https://nodejs.org/)，并保证 Node.js 版本不低于 v20.19.5，**我们推荐使用 Node.js 22 的 LTS 版本**。
 
 你可以通过以下命令检查当前使用的 Node.js 版本：
 
@@ -6,9 +6,9 @@
 node -v
 ```
 
-如果你当前的环境中尚未安装 Node.js，或是安装的版本低于 18，可以通过 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 安装需要的版本。
+如果你当前的环境中尚未安装 Node.js，或是安装的版本低于 v20.19.5，可以通过 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 安装需要的版本。
 
- 下面是通过 nvm 安装 Node.js 22 LTS 版本的例子：
+下面是通过 nvm 安装 Node.js 22 LTS 版本的例子：
 
 ```bash
 # 安装 Node.js 22 的长期支持版本
@@ -26,7 +26,3 @@ nvm 和 fnm 都是 Node.js 版本管理工具。相对来说，nvm 较为成熟
 :::
 
 此外，在安装 nvm 或 fnm 后，然后只要仓库根目录下有内容为 `lts/jod` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
-
-:::warning
-Modern.js 目前仍支持 Node 16，但会在 2025 年 6 月正式终止对 Node.js 16 的支持，为确保您的项目顺利过渡，请在 2025 年 6 月前完成 Node.js 版本升级。
-:::

package/docs/zh/components/prerequisites.mdx

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

package/docs/zh/components/self-route-example.mdx

@@ -1,13 +1,13 @@
 ```tsx title="src/App.tsx"
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
 import { StaticRouter } from '@modern-js/runtime/router/server';
-import React from 'react';
-import { useRuntimeContext } from '@modern-js/runtime';
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
 
 const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
 
 export default () => {
-  const { context } = useRuntimeContext();
+  const context = use(RuntimeContext);
   const pathname = context?.request?.pathname;
   return (
     <Router location={pathname}>

package/docs/zh/components/ua-polyfill.mdx

@@ -5,14 +5,19 @@ Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-C
 - 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
 - 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
 
-可以通过微生成器开启该功能：
+Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：
 
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「基于 UA 的 Polyfill」功能
-```
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
 
-执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
+然后在 `modern.config.ts` 中注册 Polyfill 插件:
 
 ```ts title="modern.config.ts"
 import { polyfillPlugin } from '@modern-js/plugin-polyfill';

package/docs/zh/configure/_meta.json

@@ -32,20 +32,20 @@
   },
   {
     "type": "dir",
-    "name": "app/server",
-    "label": "server",
+    "name": "app/resolve",
+    "label": "resolve",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/output",
-    "label": "output",
+    "name": "app/server",
+    "label": "server",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/deploy",
-    "label": "deploy",
+    "name": "app/output",
+    "label": "output",
     "collapsed": true
   },
   "app/plugins",
@@ -73,6 +73,5 @@
     "label": "experiments",
     "collapsed": true
   },
-  "app/builder-plugins",
-  "app/auto-load-plugin"
+  "app/builder-plugins"
 ]

package/docs/zh/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+该配置用于启用 BFF 跨项目调用功能。启用后，可以将当前项目作为 BFF 生产端，生成可被其他项目直接调用的 SDK。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+有关 BFF 跨项目调用的详细配置和使用方法，请参考 [BFF 跨项目调用指南](/guides/advanced-features/bff/cross-project.html)。

package/docs/zh/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,44 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **类型：**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * 为 entries 启用 lazy compilation
+       */
+      entries?: boolean;
+      /**
+       * 为 dynamic imports 启用 lazy compilation
+       */
+      imports?: boolean;
+      /**
+       * 指定哪些导入的模块应该被延迟编译
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * 指定一个自定义的运行时代码路径，用于覆盖默认的 lazy compilation client
+       */
+      client?: string;
+      /**
+       * 指定 client 需要请求的 server URL
+       */
+      serverUrl?: string;
+    };
+```
+
+- **默认值：** `false`
+
+用于开启 lazy compilation（即按需编译），基于 Rspack 的 [lazy compilation](https://rspack.rs/zh/guide/features/lazy-compilation) 特性实现。
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致，详细信息可参考 <RsbuildLink configName="dev.lazyCompilation"/>。
+:::

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

@@ -0,0 +1,104 @@
+---
+title: server
+---
+
+# dev.server
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+通过 `dev.server` 可以修改开发环境服务器的配置。
+
+### compress
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否对静态资源启用 gzip 压缩。
+
+如果你需要禁用 gzip 压缩，可以将 `compress` 设置为 `false`：
+
+```ts
+export default {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.compress](https://rsbuild.rs/zh/config/server/compress) 文档。
+
+### headers
+
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+设置自定义响应头。
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.headers](https://rsbuild.rs/zh/config/server/headers) 文档。
+
+### historyApiFallback
+
+- **类型：** `boolean | ConnectHistoryApiFallbackOptions`
+- **默认值：** `false`
+
+在需要对一些 404 响应或其他请求提供替代页面的场景，可通过 `dev.server.historyApiFallback` 进行设置：
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+
+更多配置选项请参考 [Rsbuild - server.historyApiFallback](https://rsbuild.rs/zh/config/server/history-api-fallback) 文档。
+
+### watch
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否监听 `mock/`、`server/`、`api/` 等目录的文件变化。
+
+更多详细信息请参考 [Rsbuild - dev.watchFiles](https://rsbuild.rs/zh/config/dev/watch-files) 文档。
+
+### cors
+
+- **类型:** `boolean | import('cors').CorsOptions`
+
+为开发服务器配置 CORS（跨域资源共享）。
+
+Modern.js 中 `cors` 的默认配置遵循 Rsbuild 的默认值：
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // 默认允许：
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins
+};
+```
+
+更多配置选项和详细用法请参考 [Rsbuild - server.cors](https://rsbuild.rs/zh/config/server/cors) 文档。

package/docs/zh/configure/app/dev/setup-middlewares.mdx

@@ -7,32 +7,13 @@ title: setupMiddlewares
 - **类型：**
 
 ```ts
-type SetupMiddlewaresServer = {
+type RequestHandler = (req: any, res: any, next: () => void) => void;
+
+type ExposeServerApis = {
   sockWrite: (
     type: string,
     data?: string | boolean | Record<string, any>,
   ) => void;
-  environments: {
-    [name: string]: {
-      /**
-       * 获取当前环境的构建信息
-       */
-      getStats: () => Promise<Stats>;
-
-      /**
-       * 在服务端加载并执行构建产物
-       *
-       * @param entryName - 入口名称，和 Rsbuild source.entry 的某一个 key 值对应
-       * @returns 入口模块的返回值
-       */
-      loadBundle: <T = unknown>(entryName: string) => Promise<T>;
-
-      /**
-       * 获取编译后的 HTML 模版内容
-       */
-      getTransformedHtml: (entryName: string) => Promise<string>;
-    };
-  };
 };
 
 type SetupMiddlewares = Array<
@@ -41,7 +22,7 @@ type SetupMiddlewares = Array<
       unshift: (...handlers: RequestHandler[]) => void;
       push: (...handlers: RequestHandler[]) => void;
     },
-    server: SetupMiddlewaresServer,
+    server: ExposeServerApis,
   ) => void
 >;
 ```

package/docs/zh/configure/app/html/app-icon.mdx

@@ -13,7 +13,7 @@ type AppIconItem = {
   target?: 'apple-touch-icon' | 'web-app-manifest';
 };
 
-type AppIcon = string | {
+type AppIcon = {
   name?: string;
   icons: AppIconItem[];
   filename?: string;
@@ -27,28 +27,6 @@ type AppIcon = string | {
 - 生成 web app manifest 文件和其中的 `icons` 字段。
 - 生成 HTML 文件中的 `apple-touch-icon` 标签和 `manifest` 标签。
 
-### 字符串形式
-
-`string` 类型的 `appIcon` 配置是对象类型的一个语法糖。
-
-```js
-export default {
-  html: {
-    appIcon: './src/assets/icon.png',
-  },
-};
-```
-
-以上配置相当于下面配置的语法糖：
-
-```js
-export default {
-  html: {
-    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
-  },
-};
-```
-
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="html.appIcon" />

package/docs/zh/configure/app/output/inline-scripts.mdx

@@ -20,7 +20,7 @@ type InlineScripts =
     };
 ```
 
-- **默认值：** `false`
+- **默认值：** `/builder-runtime([.].+)?\.js$/`
 
 用来控制是否用 `<script>` 标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。
 

package/docs/zh/configure/app/output/override-browserslist.mdx

@@ -9,9 +9,9 @@ title: overrideBrowserslist
 
 ```ts
 const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
-  web: ['> 0.01%', 'not dead', 'not op_mini all'],
+  web: ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
   node: ['node >= 14'],
-  'web-worker': ['> 0.01%', 'not dead', 'not op_mini all'],
+  'web-worker': ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
 };
 ```
 
@@ -19,7 +19,7 @@ const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
 
 该值会被 [SWC](https://github.com/swc-project/swc) 和 [autoprefixer](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
 
-Modern.js 会优先使用项目根目录的 `.browserslistrc` 文件中的配置。
+其他配置方式和配置优先级请参考 [Browserslist 配置](/guides/advanced-features/compatibility.html)。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

package/docs/zh/configure/app/output/source-map.mdx

@@ -15,17 +15,24 @@ type SourceMap =
     };
 ```
 
+用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+
 - **默认值：**
 
 ```ts
 const defaultSourceMap = {
-  js: isDev ? 'cheap-module-source-map' : false,
-  css: false,
+  js: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
+  css: isDev,
 };
 ```
 
-用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+在不配置 `output.sourceMap` 时，Modern.js 的 source map 生成规则与 Rsbuild 配置有差异：
+
+- 在开发模式构建时，会生成 JS 文件和 CSS 的 source map，便于进行开发调试。
+- 在生产模式构建时，会生成 JS 的 source map 用于堆栈回溯，不生成 CSS 文件的 source map，以提供最佳的构建性能。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="output.sourceMap" />
+
+