@modern-js/main-doc 3.9.3 → 3.10.1

package/docs/zh/guides/advanced-features/international/routing.mdx

@@ -26,9 +26,9 @@ i18nPlugin({
 
 **效果：**
 
-| 访问路径 | 结果 |
-| --- | --- |
-| `/about` | 重定向到 `/en/about` |
+| 访问路径    | 结果                  |
+| ----------- | --------------------- |
+| `/about`    | 重定向到 `/en/about`  |
 | `/en/about` | 正常访问，语言为 `en` |
 | `/zh/about` | 正常访问，语言为 `zh` |
 
@@ -108,7 +108,9 @@ function Navigation() {
     <nav>
       <I18nLink to="/">首页</I18nLink>
       <I18nLink to="/about">关于</I18nLink>
-      <I18nLink to="/contact" replace>联系</I18nLink>
+      <I18nLink to="/contact" replace>
+        联系
+      </I18nLink>
     </nav>
   );
 }

package/docs/zh/guides/advanced-features/international.mdx

@@ -10,15 +10,15 @@ import I18nPluginIntroduce from '@site-docs/components/international/introduce';
 
 ## 从哪里开始？
 
-| 想做的事 | 文档 |
-| --- | --- |
-| 首次接入，跑通示例 | [快速开始](./international/quick-start.md) |
-| 了解完整的配置选项 | [配置说明](./international/configuration.md) |
-| 根据 URL / Cookie / Header 自动判断语言 | [语言检测](./international/locale-detection.md) |
-| 实现 `/en/about` 这类带语言前缀的路径 | [路由集成](./international/routing.md) |
-| 从远程服务或平台加载翻译资源 | [资源加载 → 自定义后端](./international/resource-loading.md#sdk-后端) |
-| SSR 场景、多入口、自定义实例 | [高级用法](./international/advanced.md) |
-| 查询 Hook / 组件 / 类型定义 | [API 参考](./international/api.md) |
+| 想做的事                                | 文档                                                                  |
+| --------------------------------------- | --------------------------------------------------------------------- |
+| 首次接入，跑通示例                      | [快速开始](./international/quick-start.md)                            |
+| 了解完整的配置选项                      | [配置说明](./international/configuration.md)                          |
+| 根据 URL / Cookie / Header 自动判断语言 | [语言检测](./international/locale-detection.md)                       |
+| 实现 `/en/about` 这类带语言前缀的路径   | [路由集成](./international/routing.md)                                |
+| 从远程服务或平台加载翻译资源            | [资源加载 → 自定义后端](./international/resource-loading.md#sdk-后端) |
+| SSR 场景、多入口、自定义实例            | [高级用法](./international/advanced.md)                               |
+| 查询 Hook / 组件 / 类型定义             | [API 参考](./international/api.md)                                    |
 
 ## 核心能力
 

package/docs/zh/guides/advanced-features/server-monitor/logger.mdx

@@ -6,10 +6,10 @@
 
 基于服务端运行逻辑，Modern.js 在内部提供了以下日志事件：
 
-| 阶段          | 消息                                         | Level |
-| ------------- | -------------------------------------------- | ----- |
-| RENDER_HTML   | App Render To HTML                           | error |
-| RENDER_STREAM | An error occurs during streaming SSR         | error |
+| 阶段          | 消息                                          | Level |
+| ------------- | --------------------------------------------- | ----- |
+| RENDER_HTML   | App Render To HTML                            | error |
+| RENDER_STREAM | An error occurs during streaming SSR          | error |
 | RENDER_SHELL  | An error occurs during streaming render shell | error |
 
 ## 内置 Monitor
@@ -17,5 +17,3 @@
 import InternalLogger from '@site-docs/components/internal-logger.mdx';
 
 <InternalLogger />
-
-

package/docs/zh/guides/advanced-features/server-monitor/metrics.mdx

@@ -8,21 +8,20 @@
 
 基于服务端运行逻辑，Modern.js 在内部提供了以下指标事件：
 
-| Key                      | 描述             |
-| ------------------------ | ---------------  |
-| server-handle-request    | Modern.js Server 处理请求单次耗时                                                           |
-| ssr-render-shell         | [SSR]在使用 Streaming SSR 时， React 将渲染一个套壳(shell)优先传输。这里表明套壳渲染完成时间                              |
-| ssr-render-html          | [SSR] React 将组件树渲染成 html 所消耗的时间，通常不会超过 50ms                                                         |
-| server-middleware        | Modern.js 自定义 Server `Middleware` 执行总时                                                                           |
-| server-loader            | Server 端整体 Data Loader 耗时                                                                                     |
-| server-loader-#id        | Server 端各个 Data Loader 耗时                                                                                      |
-| server-loader-navigation | 前端导航时，服务端 Data Loader 的整体耗时                                                                              |
+| Key                      | 描述                                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| server-handle-request    | Modern.js Server 处理请求单次耗时                                                            |
+| ssr-render-shell         | [SSR]在使用 Streaming SSR 时， React 将渲染一个套壳(shell)优先传输。这里表明套壳渲染完成时间 |
+| ssr-render-html          | [SSR] React 将组件树渲染成 html 所消耗的时间，通常不会超过 50ms                              |
+| server-middleware        | Modern.js 自定义 Server `Middleware` 执行总时                                                |
+| server-loader            | Server 端整体 Data Loader 耗时                                                               |
+| server-loader-#id        | Server 端各个 Data Loader 耗时                                                               |
+| server-loader-navigation | 前端导航时，服务端 Data Loader 的整体耗时                                                    |
 
 Modern.js 服务端流程如图所示：
 
 ![server](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/edenx-website/e374def0-c179-40aa-9cfe-e82e181663b1.jpeg)
 
-
 ## 内置 Monitor
 
 import InternalMetrics from '@site-docs/components/internal-metrics.mdx';

package/docs/zh/guides/advanced-features/source-build.mdx

@@ -142,7 +142,7 @@ Project reference 提供了以下能力：
 {
   "compilerOptions": {
     "composite": true
-  },
+  }
 }
 ```
 

package/docs/zh/guides/advanced-features/web-server.mdx

@@ -50,13 +50,13 @@ export default defineServerConfig({
 
 3. 你可以将 `server` 目录包含在 `tsconfig.json` 中
 
-```json5
+```jsonc
 {
   // ...
   "include": [
     // ...
-    "server"
-  ]
+    "server",
+  ],
 }
 ```
 

package/docs/zh/guides/basic-features/data/data-fetch.mdx

@@ -25,9 +25,7 @@ Modern.js 推荐使用[约定式路由](/guides/basic-features/routes/routes)做
 在 `routes/user/page.data.ts` 文件中，可以导出一个 `loader` 函数：
 
 ```ts title="routes/user/page.data.ts"
-export type ProfileData = {
-  /*  some types */
-};
+export type ProfileData = {/*  some types */};
 
 export const loader = async (): Promise<ProfileData> => {
   const res = await fetch('https://api/user/profile');

package/docs/zh/guides/basic-features/data/data-write.mdx

@@ -33,7 +33,7 @@ export const action: ActionFunction = async ({ request }) => {
   const newUser = await request.json();
   const name = newUser.name;
   return updateUserProfile(name);
-}
+};
 ```
 
 在路由组件中，你可以通过 `useFetcher` 获取对应 `submit` 函数，执行并触发 Data Action：
@@ -43,7 +43,7 @@ import {
   useFetcher,
   useLoaderData,
   useParams,
-  Outlet
+  Outlet,
 } from '@modern-js/runtime/router';
 
 export default () => {
@@ -51,23 +51,21 @@ export default () => {
   const { submit } = useFetcher();
   const editUser = () => {
     const newUser = {
-      name: 'Modern.js'
-    }
+      name: 'Modern.js',
+    };
     return submit(newUser, {
       method: 'post',
       encType: 'application/json',
-    })
-  }
+    });
+  };
   return (
     <div>
       <button onClick={editUser}>edit user</button>
-      <div className="user-profile">
-        {userInfo}
-      </div>
+      <div className="user-profile">{userInfo}</div>
       <Outlet context={userInfo}></Outlet>
     </div>
-  )
-}
+  );
+};
 ```
 
 当执行 `submit` 后，会触发定义的 `action` 函数。在 `action` 函数中，可以通过[入参](/guides/basic-features/data/data-write.html#入参)获取提交的数据，最终发送数据到服务端。
@@ -124,17 +122,18 @@ useSubmit:
 
 ```ts
 const submit = useSubmit();
-submit(null, { method: "post", action: "/logout" });
+submit(null, { method: 'post', action: '/logout' });
 ```
 
 useFetcher:
 
 ```ts
 const { submit } = useFetcher();
-submit(null, { method: "post", action: "/logout" });
+submit(null, { method: 'post', action: '/logout' });
 ```
 
 `submit` 函数有两个入参，第一个入参是传递到服务端的 `formData`。第二个入参是可选参数，其中
+
 - `method` 相当于表单提交时的 `method`，大部分写入数据的场景下，`method` 可以传入 `post`。
 - `action` 用来指定触发哪个路由组件的 Data Action，如果未传入 `action` 入参，默认会触发当前路由组件的 action，即 `user/page.tsx` 组件或子组件中执行 submit，会触发 `user/page.data.ts` 中定义的 action。
 
@@ -144,7 +143,6 @@ submit(null, { method: "post", action: "/logout" });
 
 :::
 
-
 ### 数据类型
 
 `submit` 函数的第一个入参，可以接受不同类型的值。
@@ -153,7 +151,7 @@ submit(null, { method: "post", action: "/logout" });
 
 ```ts
 let formData = new FormData();
-formData.append("cheese", "gouda");
+formData.append('cheese', 'gouda');
 submit(formData);
 // In the action, you can get the data by request.json
 ```
@@ -162,7 +160,7 @@ submit(formData);
 
 ```ts
 let searchParams = new URLSearchParams();
-searchParams.append("cheese", "gouda");
+searchParams.append('cheese', 'gouda');
 submit(searchParams);
 // In the action, you can get the data by request.json
 ```
@@ -170,10 +168,10 @@ submit(searchParams);
 或任意 `URLSearchParams` 构造函数可接受的值：
 
 ```ts
-submit("cheese=gouda&toasted=yes");
+submit('cheese=gouda&toasted=yes');
 submit([
-  ["cheese", "gouda"],
-  ["toasted", "yes"],
+  ['cheese', 'gouda'],
+  ['toasted', 'yes'],
 ]);
 // In the action, you can get the data by request.json
 ```
@@ -182,11 +180,11 @@ submit([
 
 ```ts
 submit(
-  { key: "value" },
+  { key: 'value' },
   {
-    method: "post",
-    encType: "application/x-www-form-urlencoded",
-  }
+    method: 'post',
+    encType: 'application/x-www-form-urlencoded',
+  },
 );
 
 // In the action, you can get the data by request.formData
@@ -195,14 +193,11 @@ submit(
 你也可以通过第二个参数，指定为编码方式：
 
 ```tsx
-submit(
-  { key: "value" },
-  { method: "post", encType: "application/json" }
-);
+submit({ key: 'value' }, { method: 'post', encType: 'application/json' });
 
 submit('{"key":"value"}', {
-  method: "post",
-  encType: "application/json",
+  method: 'post',
+  encType: 'application/json',
 });
 
 // In the action, you can get the data by request.json
@@ -211,7 +206,7 @@ submit('{"key":"value"}', {
 或提交纯文本：
 
 ```ts
-submit("value", { method: "post", encType: "text/plain" });
+submit('value', { method: 'post', encType: 'text/plain' });
 // In the action, you can get the data by request.text
 ```
 
@@ -228,7 +223,6 @@ Modern.js 中提供 Data Action 主要是为了使 UI 和服务器的状态能
 
 如果项目中组件共享的数据主要来自于服务端的状态，则无需在项目引入浏览器端状态管理库。可以使用 Data Loader 请求数据，通过 [`useRouteLoaderData`](/guides/basic-features/data/data-fetch.md) 在子组件中共享数据，使用 Data Action 修改和同步服务端的状态。
 
-
 ## CSR 和 SSR
 
 与 Data Loader 一样，SSR 项目中，Data Action 是在服务端执行的（框架会自动发请求触发 Data Action），而在 CSR 项目中，Data Action 是在浏览器端执行的。

package/docs/zh/guides/basic-features/debug/mock.mdx

@@ -101,8 +101,8 @@ type MockConfig = {
 };
 
 export const config = {
-  enable: false
-}
+  enable: false,
+};
 ```
 
 目前仅支持 `enable` 配置，开发者可以通过该配置控制是否执行 Mock。

package/docs/zh/guides/basic-features/debug/using-storybook.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 15
 ---
 
-import { PackageManagerTabs } from '@theme'
+import { PackageManagerTabs } from '@theme';
 
 # 使用 Storybook
 
@@ -33,14 +33,14 @@ Modern.js 基于此工具实现了 `storybook-addon-modernjs`，该插件会加
 ## 配置 `.storybook/main.ts`
 
 ```ts
-import type { StorybookConfig } from 'storybook-react-rsbuild'
+import type { StorybookConfig } from 'storybook-react-rsbuild';
 
 const config: StorybookConfig = {
   stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
   addons: ['storybook-addon-modernjs'],
   framework: 'storybook-react-rsbuild',
-}
-export default config
+};
+export default config;
 ```
 
 ## Storybook 中进行 BFF 一体化调用
@@ -55,7 +55,7 @@ export default config
 {
   "scripts": {
     "dev:api": "modern dev --api-only",
-    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open",
+    "storybook": "BFF_PROXY=1 storybook dev -p 6006 --no-open"
   }
 }
 ```

package/docs/zh/guides/basic-features/env-vars.mdx

@@ -72,7 +72,6 @@ function App() {
 
 :::
 
-
 ## 自定义环境变量
 
 环境变量支持通过 `shell` 和 `.env` 文件两种方式指定。

package/docs/zh/guides/basic-features/html.mdx

@@ -20,9 +20,8 @@ Modern.js 约定，在 `src/` 或入口目录下，可以创建 `Document.tsx`
     ├── entry-a
     │   ├── Document.tsx
     │   └── routes
-    ├── entry-b
-    │    └── routes
-    └── modern-app-env.d.ts
+    └── entry-b
+         └── routes
 ```
 
 `entry-a` 会优先使用当前入口下的 `Document.tsx` 文件。如果当前入口没有 `Document.tsx` 文件，例如 `entry-b`，则会查找根目录下的 `Document.tsx` 文件。

package/docs/zh/guides/basic-features/render/overview.mdx

@@ -8,21 +8,21 @@ Modern.js 支持多种渲染模式，不同的渲染模式适用于不同的场
 
 ## 渲染模式速览
 
-| 渲染模式 | 特点 | 适用场景 |
-|---------|------|---------|
-| **CSR** | 在浏览器端执行 JavaScript 渲染页面 | 交互性强、对 SEO 要求不高的应用 |
-| **SSR** | 在服务端预先渲染完整 HTML 页面 | 对首屏性能和 SEO 要求高的网站 |
-| **Streaming SSR** | 边渲染边返回，更快显示初始 UI | 需要更快首屏感知速度的应用（**SSR 默认模式**） |
-| **RSC** | 组件在服务端渲染，减少客户端 JS 体积；数据与组件逻辑高内聚，减少状态传递 | 追求极致性能、需要减少客户端代码的项目 |
-| **SSG** | 构建时生成静态页面，可被 CDN 缓存 | 内容相对静态的网站，如博客、文档站点 |
+| 渲染模式          | 特点                                                                     | 适用场景                                       |
+| ----------------- | ------------------------------------------------------------------------ | ---------------------------------------------- |
+| **CSR**           | 在浏览器端执行 JavaScript 渲染页面                                       | 交互性强、对 SEO 要求不高的应用                |
+| **SSR**           | 在服务端预先渲染完整 HTML 页面                                           | 对首屏性能和 SEO 要求高的网站                  |
+| **Streaming SSR** | 边渲染边返回，更快显示初始 UI                                            | 需要更快首屏感知速度的应用（**SSR 默认模式**） |
+| **RSC**           | 组件在服务端渲染，减少客户端 JS 体积；数据与组件逻辑高内聚，减少状态传递 | 追求极致性能、需要减少客户端代码的项目         |
+| **SSG**           | 构建时生成静态页面，可被 CDN 缓存                                        | 内容相对静态的网站，如博客、文档站点           |
 
 ## 性能对比
 
-| 渲染技术 | 核心优势 | 主要瓶颈 |
-|---------|---------|---------|
-| **SSR** | 服务端预渲染，有利于 SEO | 需等待所有数据加载完成才能响应 |
-| **Streaming SSR** | 边渲染边返回，更快首屏 | JS 体积仍然较大 |
-| **Streaming SSR + RSC** | 减少客户端 JS 体积 | - |
+| 渲染技术                | 核心优势                 | 主要瓶颈                       |
+| ----------------------- | ------------------------ | ------------------------------ |
+| **SSR**                 | 服务端预渲染，有利于 SEO | 需等待所有数据加载完成才能响应 |
+| **Streaming SSR**       | 边渲染边返回，更快首屏   | JS 体积仍然较大                |
+| **Streaming SSR + RSC** | 减少客户端 JS 体积       | -                              |
 
 ## 如何选择
 
@@ -42,7 +42,6 @@ Modern.js 支持多种渲染模式组合使用：
 - **SSG + SSR**：部分页面静态，部分页面动态
 - **CSR + RSC**：客户端渲染 + 部分 Server Component
 
-
 ## 相关文档
 
 - [服务端渲染（SSR）](/guides/basic-features/render/ssr)

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -239,12 +239,12 @@ export default function DashboardPage() {
 
 ### 两种数据获取方式对比
 
-| 特性 | Server Component 中获取 | Data Loader 中获取 |
-| --- | --- | --- |
-| 避免请求瀑布 | 需要手动优化 | ✅ 自动并行执行 |
-| 组件内聚性 | ✅ 数据和 UI 在同一处 | 数据逻辑分离到单独文件 |
-| 维护性 | ✅ 更易理解和维护 | 需要维护额外文件 |
-| 类型安全 | ✅ 天然类型推断 | 需要手动管理类型 |
+| 特性         | Server Component 中获取 | Data Loader 中获取     |
+| ------------ | ----------------------- | ---------------------- |
+| 避免请求瀑布 | 需要手动优化            | ✅ 自动并行执行        |
+| 组件内聚性   | ✅ 数据和 UI 在同一处   | 数据逻辑分离到单独文件 |
+| 维护性       | ✅ 更易理解和维护       | 需要维护额外文件       |
+| 类型安全     | ✅ 天然类型推断         | 需要手动管理类型       |
 
 **一般情况下，我们推荐在 Server Component 中获取数据**，因为在服务端瀑布请求对性能的影响较小，这种方式使组件更加内聚，数据获取逻辑和 UI 渲染在同一处，更易于理解和维护。但如果你的页面有多个独立的数据源，且希望完全避免请求瀑布问题，Data Loader 的并行执行特性会更有优势。
 
@@ -268,7 +268,11 @@ export default function DashboardPage() {
 
 ```tsx title="routes/user/page.tsx"
 // Server Component 通过 props 接收 loaderData
-export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
+export default function UserPage({
+  loaderData,
+}: {
+  loaderData: { name: string };
+}) {
   return <div>Welcome, {loaderData.name}</div>;
 }
 ```
@@ -276,7 +280,11 @@ export default function UserPage({ loaderData }: { loaderData: { name: string }
 ```tsx title="routes/user/page.tsx"
 'use client';
 // Client Component 同样可以通过 props 接收 loaderData
-export default function UserPage({ loaderData }: { loaderData: { name: string } }) {
+export default function UserPage({
+  loaderData,
+}: {
+  loaderData: { name: string };
+}) {
   return <div>Welcome, {loaderData.name}</div>;
 }
 ```
@@ -600,7 +608,6 @@ export default function ProfilePage() {
 
 import DeployTip from '@site-docs/components/rsc-deploy-tip';
 
-
 <DeployTip />
 
 ## 常见问题

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

@@ -74,10 +74,8 @@ export default () => {
 };
 ```
 
-
 ### 使用 Client Loader
 
-
 默认情况下，在 SSR 应用中，`loader` 函数只会在服务端执行。但有些场景下，开发者可能期望在浏览器端发送的请求不经过 SSR 服务，直接请求数据源，例如：
 
 1. 在浏览器端希望减少网络消耗，直接请求数据源。
@@ -96,12 +94,10 @@ export async function loader({ params }) {
   const data = await res.json();
   return {
     message: data.message,
-  }
+  };
 }
 ```
 
-
-
 ## SSR 降级
 
 在 Modern.js 中，如果应用在 SSR 过程中出现异常，Modern.js 会自动降级到 CSR 模式，并在 CSR 重新发起数据请求，保证页面能够正常展示。SSR 降级的原因主要分为两种：
@@ -133,11 +129,7 @@ const Page = () => {
   const undefinedVars = data.unDefined;
   const definedVars = data.defined;
 
-  return (
-    <div>
-      {isNode ? undefinedVars.msg : definedVars.msg}
-    </div>
-  );
+  return <div>{isNode ? undefinedVars.msg : definedVars.msg}</div>;
 };
 
 export default Page;
@@ -222,7 +214,7 @@ document.addEventListener('load', () => {
   console.log('document load');
 });
 
-export const doSomething = () => {}
+export const doSomething = () => {};
 ```
 
 如果直接引用到组件中，会造成 SSR 加载报错，即使你已经使用环境变量进行判断，但仍然无法移除依赖中副作用的执行。
@@ -234,8 +226,8 @@ export const Page = () => {
   if (process.env.MODERN_TARGET === 'browser') {
     doSomething();
   }
-  return <div>Hello World</div>
-}
+  return <div>Hello World</div>;
+};
 ```
 
 Modern.js 也支持通过 `.server.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。可以创建同名的 `.ts` 和 `.server.ts` 文件做一层代理：
@@ -251,12 +243,12 @@ export const doSomething: any = () => {};
 在文件中直接引入 `./a`，此时 SSR 打包下会优先使用 `.server.ts` 后缀的文件，CSR 打包下会使用 `.ts` 后缀的文件。
 
 ```tsx title="routes/page.tsx"
-import { doSomething } from './a'
+import { doSomething } from './a';
 
 export const Page = () => {
   doSomething();
-  return <div>Hello World</div>
-}
+  return <div>Hello World</div>;
+};
 ```
 
 ## 常见问题
@@ -331,4 +323,3 @@ export default function Test() {
 在浏览器端，这段代码不会造成任何问题，但是在 SSR 时，Middleware 实例会一直无法被销毁。每次渲染组件，调用 `epicMiddleware.run(rootEpic)` 时，都会在内部添加新的事件绑定，导致整个对象不断变大，最终对应用性能造成影响。
 
 CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不确定应用是否存在这类隐患，可以对应用进行压测。
-