@modern-js/main-doc 2.22.1 → 2.23.1

package/docs/en/tutorials/first-app/c03-css.mdx

@@ -5,7 +5,7 @@ title: Add Style
 
 import { Tabs, Tab as TabItem } from "@theme";
 
-In the previous chapter, we learned how to use components from the three-way library.
+In the previous chapter, we learned how to use components from the third-party library.
 
 In this chapter, we will learn how to implement UI components.
 

package/docs/zh/apis/app/commands.mdx

@@ -106,12 +106,13 @@ File sizes after production build:
 
 `modern new` 命令用于在已有项目中添加项目元素。
 
-比如添加应用入口、启用启用一些可选功能如 Tailwind CSS、微前端开发模式等。
+比如添加应用入口、启用一些可选功能如 Tailwind CSS、微前端开发模式等。
 
 ```bash
 Usage: modern new [options]
 
 Options:
+  --lang <lang>          设置 new 命令执行语言(zh 或者 en)
   -d, --debug            开启 Debug 模式，打印调试日志信息 (default: false)
   -c, --config <config>  生成器运行默认配置(JSON 字符串)
   --dist-tag <tag>       生成器使用特殊的 npm Tag 版本
@@ -162,7 +163,6 @@ Usage: modern serve [options]
 Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help            显示命令帮助
-  --web-only            仅启动 Web 服务
   --api-only            仅启动 API 接口服务
 ```
 
@@ -180,7 +180,7 @@ export default defineConfig({
 
 在项目根目录下执行命令 `npx modern upgrade`，会默认将当前执行命令项目的 `package.json` 中的 Modern.js 相关依赖更新至最新版本。
 
-```
+```bash
 Usage: modern upgrade [options]
 
 Options:
@@ -194,7 +194,7 @@ Options:
 
 `modern inspect` 命令用于查看项目的 [Modern.js Builder 配置](https://modernjs.dev/builder/guide/basic/builder-config.html) 以及 webpack 配置。
 
-```
+```bash
 Usage: modern inspect [options]
 
 Options:

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

@@ -2,6 +2,7 @@
 title: storybook/
 sidebar_position: 7
 ---
+
 # storybook/
 
 Modern.js 支持使用 Storybook 进行调试，当需要对 Storybook 进行配置时，需要在项目 config/storybook 目录进行配置。
@@ -12,3 +13,26 @@ Storybook 配置请查看：[Storybook 配置](https://storybook.js.org/docs/rea
 使用 Storybook 进行调试需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式功能。
 
 :::
+
+### 示例
+
+对于 Storybook Manager app 部分的 webpack 配置，可以通过增加 `./config/storybook/main.js` 文件进行配置。
+
+```js
+// ./config/storybook/main.js
+
+module.exports = {
+  // it controls the Storybook manager app
+  managerWebpack: async (config, options) => {
+    // update config here
+    return config;
+  },
+};
+```
+
+### 限制
+
+在使用 config/storybook 目录进行配置时，存在以下限制：
+
+- 不能修改 Story 文件存放的位置，即无法在 `main.js` 文件里修改 `stories` 配置。
+- 不支持在 `main.js` 中修改 Webpack 和 Babel 相关配置，相关需求可通过 [`tools.webpack`](/configure/app/tools/webpack.html) / [`tools.babel`](/configure/app/tools/babel.html) 修改。

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

@@ -6,7 +6,7 @@ sidebar_position: 7
 
 应用项目 Storybook 调试文件。
 
-可以在项目源码目录 `src/` 下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
+可以在项目源码目录 `src/` 下创建 `*.stories.(js|jsx|ts|tsx|mdx)` 格式的文件作为 Storybook 的调试文件。
 
 在项目下执行 `npm run dev story` 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
 

package/docs/zh/apis/app/runtime/testing/render.mdx

@@ -41,7 +41,7 @@ function render(ui: React.ReactElement<any>, options: Options): RenderResult;
 - `options`：render 可选配置。
   - `container`：表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
   - `baseElement`：用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
-  - `hydrate`：如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) 渲染组件。默认值为 `false`。
+  - `hydrate`：如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://zh-hans.react.dev/reference/react-dom/hydrate) 渲染组件。默认值为 `false`。
   - `wrapper`：是一个 react 组件，可用于自定义渲染逻辑。
   - `queries`：自定义一些自己的 `queries`。
 

package/docs/zh/components/bff-proxy-path-rewrite.mdx

@@ -0,0 +1,16 @@
+这里还可以进行路径重写，如将发送到 `localhost:8080/api/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
+
+```ts title="modern.server-runtime.config.ts"
+import { defineConfig } from '@modern-js/app-tools/server';
+export default defineConfig({
+  bff: {
+    proxy: {
+      '/api': {
+        target: 'https://cnodejs.org',
+        pathRewrite: { '/api/topics': '/api/v1/topics' },
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```

package/docs/zh/components/bff-proxy-principle.mdx

@@ -0,0 +1 @@
+BFF Proxy 使用了强大的 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)，如果需要更多高级的用法， 可以查看它的[文档](https://github.com/chimurai/http-proxy-middleware#options)。

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

@@ -0,0 +1,4 @@
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+
+:::

package/docs/zh/components/global-proxy-config.mdx

@@ -1,14 +1,37 @@
 - **类型：** `string | Object`
 - **默认值：** `null`
 
-配置该选项后，开发环境时会启动全局代理，类似 [Fiddler](https://www.telerik.com/fiddler), [Charles](https://www.charlesproxy.com/) 等 web 代理调试工具，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
+该选项用于在开发环境下启用基于 [whistle](https://wproxy.org/whistle/) 的全局代理，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
 
-:::tip 提示
-使用该选项需要提前安装 `@modern-js/plugin-proxy`。
+### 注册插件
 
-:::
+使用该选项前，你需要提前安装和注册 `@modern-js/plugin-proxy` 插件：
+
+```bash
+# npm
+npm add @modern-js/plugin-proxy -D
+
+# yarn
+yarn add @modern-js/plugin-proxy -D
+
+# pnpm
+pnpm add @modern-js/plugin-proxy -D
+```
+
+安装完成后，在 `modern.config.ts` 文件中注册插件：
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import proxyPlugin from '@modern-js/plugin-proxy';
+
+export default defineConfig({
+  plugins: [appTools(), proxyPlugin()],
+});
+```
 
-值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
+### Object 类型
+
+`dev.proxy` 的值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
 
 例如：
 
@@ -24,7 +47,11 @@ export default defineConfig({
 });
 ```
 
-值为 `string` 时， 可以用来指定单独的代理文件，例如：
+请参考 [whistle - 匹配模式](https://wproxy.org/whistle/pattern.html) 来了解详细用法。
+
+### String 类型
+
+`dev.proxy` 的值为 `string` 时， 可以用来指定单独的代理文件，例如：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -43,10 +70,7 @@ module.exports = {
 };
 ```
 
-:::info
-Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/), 更多匹配模式请参考: [匹配模式](https://wproxy.org/whistle/pattern.html)
-
-:::
+### 启动代理
 
 执行 `dev`, 提示如下时，即代理服务器启动成功：
 
@@ -64,7 +88,7 @@ Modern.js 全局代理实现底层基于 [whistle](https://wproxy.org/whistle/),
 
 ![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
 
-:::caution 注意
+:::info
 https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
 
 :::

package/docs/zh/configure/app/bff/enable-handle-web.mdx

@@ -7,9 +7,9 @@ title: enableHandleWeb
 - **类型：** `boolean`
 - **默认值：** `false`
 
-:::caution 注意
-请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
-:::
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
 
 默认情况下，BFF 服务只能处理 BFF API 的请求。
 

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

@@ -7,10 +7,9 @@ sidebar_label: prefix
 - **类型：** `string`
 - **默认值：** `/api`
 
-:::caution 注意
-请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 
-:::
+<EnableBFFCaution />
 
 默认情况下，BFF API 目录下的路由访问前缀是 `/api`, 如下目录结构：
 

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

@@ -7,13 +7,11 @@ sidebar_label: proxy
 - **类型：** `Record<string, string>`
 - **默认值：** `{}`
 
-:::info 补充信息
-请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 
-:::
+<EnableBFFCaution />
 
-通过简单配置，无需编写代码，Modern.js 会自动转发请求。发送给 Modern.js BFF server 的请求，会代理到指定的服务上。
-BFF Proxy 使用了强大的 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)，如果需要更多高级的用法， 可以查看它的[文档](https://github.com/chimurai/http-proxy-middleware#options)。
+通过简单配置，Modern.js 可以将发送给 BFF server 的请求，自动代理到指定的服务上。
 
 在 `modern.server-runtime.config.js` 中加入以下配置；即可开启代理：
 
@@ -28,27 +26,18 @@ export default defineConfig({
 });
 ```
 
-假设启动的 Modern.js BFF server 的服务地址是 `localhost:8080`，所有 path 以 `api` 开头的请求都会被拦截，如发送到 `localhost:8080/api/v1/topics` 的请求会被代理到 `https://cnodejs.org/api/v1/topics`。
+假设 Modern.js BFF server 的地址是 `localhost:8080`，所有以 `api` 开头的请求都会被代理到 `https://cnodejs.org`，如 `localhost:8080/api/v1/topics` 的请求会被代理到 `https://cnodejs.org/api/v1/topics`。
 
-你可以做路径的重写，如将发送到 `localhost:8080/api/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
+import BFFProxyPathRewrite from "@site-docs/components/bff-proxy-path-rewrite";
 
-```ts title="modern.server-runtime.config.ts"
-import { defineConfig } from '@modern-js/app-tools/server';
-export default defineConfig({
-  bff: {
-    proxy: {
-      '/api': {
-        target: 'https://cnodejs.org',
-        pathRewrite: { '/api/topics': '/api/v1/topics' },
-        changeOrigin: true,
-      },
-    },
-  },
-});
-```
+<BFFProxyPathRewrite />
 
 与 [dev.proxy](/configure/app/dev/proxy) 不同，本节所介绍的代理只作用于进入 BFF/API 服务的请求；同时，这一配置不但可以在开发环境中使用，在生产环境中也会代理相应的请求。
 
+import BFFProxyPrinciple from "@site-docs/components/bff-proxy-principle";
+
+<BFFProxyPrinciple />
+
 ## 常见用法
 
 ### 解决接口跨域问题
@@ -72,3 +61,4 @@ export default defineServerConfig({
   },
 };
 ```
+

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

@@ -87,7 +87,7 @@ Runtime 插件运行时配置和直接在 `modern.config.ts` 中的配置默认
 :::
 
 :::warning
-defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `package.json` 中的 `modernConfig` 或者 `modern.config.ts` 中的配置决定。
+defineConfig 中只能定义 Runtime 插件的具体配置内容，确认是否开启插件还需要通过 `modern.config.ts` 中的配置决定。
 
 :::
 

package/docs/zh/configure/app/server/base-url.mdx

@@ -7,7 +7,7 @@ sidebar_label: baseUrl
 - **类型：** `string | string[]`
 - **默认值：** `undefined`
 
-统一设置服务端路由前缀（常用于共享域名的情况，区分流量)。
+统一设置服务端路由前缀（常用于多个应用共享同一域名的情况，区分流量)。
 
 ```ts title="modern.config.ts"
 export default defineConfig({

package/docs/zh/configure/app/server/public-routes.mdx

@@ -5,11 +5,11 @@ sidebar_label: publicRoutes
 # server.publicRoutes
 
 - **类型：** `Object`
-- **默认值：** 根据文件约定自动生成的服务端路由规则：应用的每个文件生成一条路由规则。
+- **默认值：** 根据文件约定自动生成的服务端路由规则，每个文件生成一条路由规则。
 
 该配置选项只作用于服务端路由，可以自定义 `config/public/` 下资源的访问路由。
 
-对象的 `key` 为当前应用的相对文件路径（不使用 `./`）, 值可以是 `string`。
+对象的 `key` 为 `config/public/` 的相对文件路径（不使用 `./`）, 值可以是 `string`。
 
 ```ts title="modern.config.ts"
 export default defineConfig({

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

@@ -5,9 +5,9 @@ sidebar_label: routes
 # server.routes
 
 - **类型：** `Object`
-- **默认值：** 根据文件约定自动生成的服务端路由规则：应用的每个入口生成一条路由规则，入口名称等于路由名称。
+- **默认值：** 根据文件约定自动生成的服务端路由规则，每个入口生成一条路由规则，入口名称等于路由路径。
 
-该配置选项只作用于服务端路由，可以自定义应用入口的服务访问配置。
+该配置选项只作用于服务端路由，可以自定义应用入口的访问路由。
 
 ## 自定义访问路由
 

package/docs/zh/configure/app/server/ssr-by-entries.mdx

@@ -7,7 +7,7 @@ sidebar_label: ssrByEntries
 - **类型：** `Object`
 - **默认值：** `undefined`
 
-按入口设置 ssr 选项，选项内的属性同 [ssr](./ssr.mdx)，指定值会和 ssr 属性内容做替换合并操作，例如：
+按入口设置 SSR 选项，选项内的属性同 [ssr](./ssr.mdx)，指定值会和 SSR 属性内容做替换合并操作，例如：
 
 :::info
 「 入口名 」默认为目录名，少数情况下通过 `source.entries` 自定义入口时，入口名为 `source.entries` 对象的 `key`。
@@ -19,11 +19,11 @@ export default defineConfig({
   server: {
     ssr: true,
     ssrByEntries: {
-      // page-a 不启用 ssr
+      // page-a 不启用 SSR
       'page-a': false,
     },
   },
 });
 ```
 
-如上配置，项目整体启用了 ssr, 但是针对入口 `page-a` 关闭了 ssr 渲染能力。
+如上配置，项目整体启用了 SSR, 但是针对入口 `page-a` 关闭了 SSR 渲染能力。

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

@@ -25,7 +25,7 @@ export default defineConfig({
 
 当值类型为 `Object` 时，可以配置如下属性：
 
-- `mode`：`string = 'string'`，默认为使用 `renderToString` 渲染。配置为 'stream' 开启流式渲染。
+- `mode`：`string = 'string'`，默认为使用 `renderToString` 渲染。配置为 `stream` 开启流式渲染。
 - `forceCSR`：`boolean = false`，默认关闭强制 CSR 渲染。配置为 `true` 后，在页面访问时添加 `?csr=true` 即可强制 CSR。
 - `inlineScript`：`boolean = true`，默认情况下，SSR 的数据会以内联脚本的方式注入到 HTML 中，并且直接赋值给全局变量。配置为 `false` 后，会下发 JSON，而不是赋值给全局变量。
 

package/docs/zh/configure/app/testing/transformer.mdx

@@ -8,9 +8,12 @@ sidebar_position: 1
 - **类型：** `'babel-jest' | 'ts-jest'`
 - **默认值：** `babel-jest`
 
-配置执行测试的时候对于源码的编译工具： [babel-jest](https://www.npmjs.com/package/babel-jest) 或 [ts-jest](https://github.com/kulshekhar/ts-jest)。默认使用 `babel-jest`。
+:::caution Caution
+请先在当前应用项目根目录使用 [new](/apis/app/commands#modern-new) 启用测试功能。
+:::
 
-:::info 补充信息
-`babel-jest` 也可以编译 TS 文件，但不会类型报错，如果你需要跑测试的时候对 TS 类型进行校验，那么请使用 `ts-jest`。
+配置执行测试时的编译工具，默认使用 `babel-jest`。可配置为 [babel-jest](https://www.npmjs.com/package/babel-jest) 或 [ts-jest](https://github.com/kulshekhar/ts-jest)。
 
+:::info 补充信息
+`babel-jest` 可以编译 TS 文件，但没有类型校验。如果你希望运行测试用例的时，能对 TS 类型进行校验，可以使用 `ts-jest`。
 :::

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

@@ -4,7 +4,7 @@ sidebar_position: 0
 
 # 配置使用
 
-Modern.js 中有两种配置，一个是编译时配置，一个是服务端运行时配置。
+Modern.js 中有两种配置，分别是编译时配置和服务端运行时配置。
 
 编译时配置可以在两个位置进行配置：
 
@@ -12,10 +12,10 @@ Modern.js 中有两种配置，一个是编译时配置，一个是服务端运
 - `package.json` 文件
 
 :::info
-Modern.js 不支持同时在 package.json 中和 modern.config.ts 中配置同一个配置项，推荐优先在 modern.config.ts 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
+Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置同一个配置项，推荐在 `modern.config.ts` 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
 :::
 
-服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中自定义配置选项。
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
 
 ## 在配置文件中配置
 
@@ -27,7 +27,7 @@ Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js`
 
 ### modern.config.ts（推荐）
 
-我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
+我们推荐使用 `.ts` 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
 从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
 
@@ -54,7 +54,7 @@ export default defineConfig({
 
 ### modern.config.js
 
-如果你在开发一个非 TypeScript 项目，可以使用 .js 格式的配置文件：
+如果你在开发一个非 TypeScript 项目，可以使用 `.js` 格式的配置文件：
 
 ```js title="modern.config.js"
 export default {
@@ -66,7 +66,7 @@ export default {
 };
 ```
 
-你也可以通过 `process.env.NODE_ENV` 进行动态设置：
+你也可以通过 `process.env.NODE_ENV`，根据环境做不同配置：
 
 ```js title="modern.config.js"
 export default {
@@ -98,7 +98,7 @@ export default defineConfig(({ env, command }) => ({
   - 当运行 `modern dev` 或 `modern start` 时，`env` 的值为 `development`。
   - 当运行 `modern build` 或 `modern serve` 时，`env` 的值为 `production`。
   - 当运行 `modern test` 时，`env` 的值为 `test`。
-- `command`: 对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
+- `command`：对应当前运行的命令，如 `dev`、`start`、`build`、`serve`。
 
 ### 导出异步函数
 
@@ -122,7 +122,7 @@ export default defineConfig(async ({ env, command }) => {
 
 Modern.js 命令行支持通过 `--config` 选项来指定配置文件的名称。
 
-例如，你需要在执行 build 命令时使用 `modern.prod.config.ts` 文件，可以在 `package.json` 中添加如下配置：
+例如，你需要在执行 `build` 命令时使用 `modern.prod.config.ts` 文件，可以在 `package.json` 中添加如下配置：
 
 ```json title="package.json"
 {
@@ -159,7 +159,7 @@ $ modern build -c modern.prod.config.js
 
 ### 注意事项
 
-- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
+- 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示错误。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
 
 ## 本地调试配置

package/docs/zh/guides/advanced-features/code-split.mdx

@@ -7,8 +7,7 @@ sidebar_position: 6
 代码分割是优化前端资源加载的一种常用手段，本文将介绍 Modern.js 支持的三种代码分割方式：
 
 :::info
-使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，包裹 `Suspense` 组件，无需自行进行代码分割。
-
+使用 Modern.js [约定式路由](/guides/basic-features/routes#约定式路由)时，默认会根据路由组件做代码分割，无需自行进行代码分割。
 :::
 
 - `import`
@@ -17,7 +16,7 @@ sidebar_position: 6
 
 ## import
 
-使用动态 `import()` 语法，`import` 接收的 JS 模块将作为一个新的打包入口被打包到单独的 JS 文件中。例如：
+使用动态 `import()` 语法，传入的 JS 模块将会被被打包到单独的 JS 文件中。例如：
 
 ```ts
 import('./math').then(math => {
@@ -25,15 +24,14 @@ import('./math').then(math => {
 });
 ```
 
-`./math` 路径对应的 JS 模块会被打包到单独的 JS 文件中。
-
 ## React.lazy
 
 React 官方提供的组件代码分割的方式。
 
 :::caution
-React 17 及以下版本不支持 SSR，建议 React17 的 SSR 应用使用 loadable。
+`React.lazy` 通常配合 `<Suspense>` 使用，因此仅在 CSR 或 React 18 Streaming SSR 中可用。
 
+对于使用传统 SSR（字符串渲染）的项目，不支持 `React.lazy`，请使用 Loadable API。
 :::
 
 ```ts
@@ -56,11 +54,11 @@ function MyComponent() {
 }
 ```
 
-`React.lazy` 更多用法请见 [React lazy](https://zh-hans.reactjs.org/docs/code-splitting.html#reactlazy)。
+`React.lazy` 更多用法请见 [React 官网文档](https://zh-hans.react.dev/reference/react/lazy)。
 
-## loadable
+## Loadable
 
-使用 `loadable` API，示例如下：
+在 Modern.js 中，可以从 `@modern-js/runtime/loadable` 中导出使用 Loadable API，示例如下：
 
 ```ts
 import loadable from '@modern-js/runtime/loadable';
@@ -72,9 +70,12 @@ function MyComponent() {
 }
 ```
 
-`loadable` 更多用法请见 [loadable API](/apis/app/runtime/utility/loadable)。
+Modern.js 开箱即用的支持在 SSR 中使用 `loadable`，无需再添加 Babel 插件，或是在 SSR 时向 HTML 中注入脚本。
 
-:::info
-`loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
+但需要注意的是，任何 Loadable API 在 SSR 中都不支持配合 `<Suspense>` 使用。
 
+:::info
+如果希望在 React 17 及以下的 CSR 项目中使用 `<Suspense>`，可以用 [loadable.lazy](https://loadable-components.com/docs/suspense/) 代替 `React.lazy`。
 :::
+
+更多用法请见 [Loadable API](/apis/app/runtime/utility/loadable)。

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

@@ -81,7 +81,6 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
     "overrides": {
       "@rspack/core": "nightly",
       "@rspack/dev-client": "nightly",
-      "@rspack/dev-middleware": "nightly",
       "@rspack/plugin-html": "nightly"
     }
   }

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

@@ -74,7 +74,7 @@ Warning: Expected server HTML to contain a matching <div> in <div>.
 这是 React 在客户端执行 hydrate 逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
 :::info
-关于 hydrate (注水)逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
+关于 hydrate (注水)逻辑请参考[这里](https://zh-hans.react.dev/reference/react-dom/hydrate)。
 
 :::
 
@@ -447,7 +447,7 @@ export default Page;
 ```
 
 `Await` 需要包裹在 `Suspense` 组件内部，`Await` 的 `resolve` 传入的是 Data Loader 异步获取的数据，当数据获取完成后，
-通过 [Render Props](https://reactjs.org/docs/render-props.html) 模式，渲染获取到的数据。在数据的获取阶段，将展示
+通过 [Render Props](https://zh-hans.react.dev/reference/react/cloneElement#passing-data-with-a-render-prop) 模式，渲染获取到的数据。在数据的获取阶段，将展示
 `Suspense` 组件 `fallback` 属性设置的内容。
 
 :::warning 注意

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

@@ -8,14 +8,14 @@ Modern.js 默认集成了 [Jest](https://jestjs.io/) 的测试能力。
 
 我们首先需要执行 `pnpm run new` 启用「单元测试 / 集成测试」功能：
 
-```
+```bash
 ? 请选择你想要的操作 启用可选功能
 ? 请选择功能名称 启用「单元测试 / 集成测试」功能
 ```
 
-执行上述命令后，`package.json` 中将会自动生成 `"test": "modern test"` 命令。
+执行上述命令后，`package.json` 中将会自动添加 `"test": "modern test"` 命令。
 
-在 `modern.config.ts` 中注册 Test 插件：
+在 `modern.config.ts` 中注册 `@modern-js/plugin-testing` 插件后即可使用测试功能：
 
 ```ts title="modern.config.ts"
 import testPlugin from '@modern-js/plugin-testing';
@@ -36,7 +36,7 @@ Modern.js 默认识别的测试文件路径为：`<rootDir>/src/**/*.test.[jt]s?
 
 Modern.js test 支持使用 [testing-library](https://testing-library.com/docs/) 相关包 API，可直接通过 `@modern-js/runtime/testing` 进行导入:
 
-```
+```ts
 import { render, screen } from '@modern-js/runtime/testing';
 ```
 

package/docs/zh/guides/advanced-features/using-storybook.mdx

@@ -0,0 +1,44 @@
+---
+sidebar_position: 20
+---
+
+# 使用 Storybook
+
+[Storybook](https://storybook.js.org/) 是一个专门用于组件调试的工具，它围绕着组件开发提供了：
+
+- 丰富多样的调试能力
+- 可与一些测试工具结合使用
+- 可重复使用的文档内容
+- 可分享能力
+- 工作流程自动化
+
+## 开启 Storybook 调试
+
+EdenX 默认集成了 Storybook 的调试能力。
+
+当我们想要对组件进行调试的时候，可以通过 `pnpm run new` 启用 Storybook 调试功能。
+
+```bash
+$ npx modern new
+? 请选择你想要的操作 启用可选功能
+? 请选择功能名称 启用「Visual Testing (Storybook)」模式
+```
+
+执行完成后，你只需在 `modern.config.ts` 文件中注册 Modern.js 的 Storybook 插件，即可启用 Storybook 调试能力。
+
+```ts title="modern.config.ts"
+import appTools, { defineConfig } from '@modern-js/app-tools';
+import storybookPlugin from '@modern-js/plugin-storybook';
+
+export default defineConfig({
+  plugins: [appTools(), storybookPlugin()],
+});
+```
+
+## 调试代码
+
+Modern.js 默认识别项目源码目录 src/ 下 [\*.stories.(js|jsx|ts|tsx|mdx)](/apis/app/hooks/src/stories.html) 格式的文件作为 Storybook 的调试文件。
+
+## 配置 Storybook
+
+在 Modern.js 中，可以在项目的 [`config/storybook`](/apis/app/hooks/config/storybook.html) 目录下增加 Storybook 配置文件。