@modern-js/main-doc 2.67.5 → 2.67.7

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

@@ -0,0 +1,44 @@
+# React Compiler
+
+React Compiler 是 React 19 引入的一个实验性编译器，它可以自动优化你的 React 代码。
+
+在开始使用 React Compiler 之前，建议阅读 [React Compiler 文档](https://zh-hans.react.dev/learn/react-compiler)，以了解 React Compiler 的功能、当前状态和使用方法。
+
+## 如何使用
+
+在 Modern.js 中使用 React Compiler 的步骤如下：
+
+1. Modern.js 目前项目还未正式支持 React 19，可以在 React 17 或 18 项目中安装 `react-compiler-runtime@rc`，以允许编译后的代码在 19 之前的版本上运行。
+
+2. 目前 React Compiler 仅提供了 Babel 插件，你需要安装 `babel-plugin-react-compiler`。
+
+3. 在你的 Modern.js 配置文件中注册 Babel 插件：
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+  },
+  tools: {
+    babel(_, { addPlugins }) {
+      addPlugins([
+        [
+          'babel-plugin-react-compiler',
+          {
+            target: '18',
+          },
+        ],
+      ]);
+    },
+  },
+  plugins: [
+    appTools({
+      bundler: 'rspack',
+    }),
+  ],
+});
+```
+
+> 详细代码可以参考：[Modern.js & React Compiler 示例项目](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/react-compiler)

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

@@ -2,22 +2,16 @@
 sidebar_position: 16
 ---
 
-# 自定义 Web Server（不推荐）
-
-:::warning
-自定义 Web Server 兼容但不再推荐使用，扩展 Server 能力请移步 [自定义 Server](/guides/advanced-features/custom-server.html)，迁移指南参考 [迁移至新版自定义 Server](/guides/advanced-features/web-server.html#%E8%BF%81%E7%A7%BB%E8%87%B3%E6%96%B0%E7%89%88%E8%87%AA%E5%AE%9A%E4%B9%89-server)。
-:::
+# 自定义 Web Server
 
 Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
 
-Modern.js 提供了 **渲染中间件（Middleware）** 与**生命周期钩子（Hook）** 两类 API 来扩展 Web Server。
+## 开启自定义 Web Server
 
-:::note
-Middleware 与 Hook 只会在用户请求页面路由时生效，BFF 路由不会经过这些 API。
+:::info
+必须确保 Modern.js 版本是 x.67.5 及以上。
 :::
 
-## 开启自定义 Web Server
-
 开发者可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Server」功能：
 
 ```bash
@@ -25,19 +19,226 @@ Middleware 与 Hook 只会在用户请求页面路由时生效，BFF 路由不
 ? 请选择创建元素类型 新建「自定义 Web Server」源码目录
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 `@modern-js/plugin-server` 插件:
+执行命令后，项目目录下会自动创建 `server/modern.server.ts` 文件，可以在这个文件中编写自定义逻辑。
+
+
+## 自定义 Web Server 能力
+
+`server/modern.server.ts` 文件中添加如下配置来扩展 Server：
+- **中间件（Middleware）**
+- **渲染中间件（RenderMiddleware）**
+- **服务端插件（Plugin）**
 
-```ts title="modern.config.ts"
-import { serverPlugin } from '@modern-js/plugin-server';
+其中 **Plugin** 中可以定义 **Middleware** 与 **RenderMiddleware**。 中间件加载流程如下图所示：
 
-export default defineConfig({
-  plugins: [..., serverPlugin()],
+<img
+  src="https://lf3-static.bytednsdoc.com/obj/eden-cn/10eh7nuhpenuhog/server-md-wf.png"
+  style={{ width: '100%', maxWidth: '540px' }}
+/>
+
+### 基本配置
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [], // 中间件
+  renderMiddlewares: [], // 渲染中间件
+  plugins: [], // 插件
 });
 ```
 
-开启功能后，项目目录下会自动创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。
 
-## 自定义 Web Server 能力
+### 类型定义
+
+`defineServerConfig` 类型定义如下:
+
+```ts
+import type { MiddlewareHandler } from 'hono';
+
+type MiddlewareObj = {
+    name: string;
+    path?: string;
+    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
+    handler: MiddlewareHandler | MiddlewareHandler[];
+};
+type ServerConfig = {
+    middlewares?: MiddlewareObj[];
+    renderMiddlewares?: MiddlewareObj[];
+    plugins?: (ServerPlugin | ServerPluginLegacy)[];
+}
+```
+
+
+### Middleware
+
+Middleware 支持在 Modern.js 服务的**请求处理**与**页面路由**的流程前后，执行自定义逻辑。
+即自定义逻辑既要处理接口路由，也要作用于页面路由，那么 Middleware 是不二选择。
+
+:::note
+如果仅需要处理 BFF 接口路由，可以通过检查 `req.path` 是否以 BFF `prefix` 开头，来判断是否为 BFF 接口请求。
+:::
+
+使用姿势如下：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  // 上报耗时
+  monitors.timing('request_timing', end - start);
+};
+
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
+```
+
+:::warning
+必须执行 `next` 函数才会执行后续的 Middleware。
+:::
+
+
+### RenderMiddleware
+
+如果只需要处理页面渲染的前后执行逻辑，modern.js 也提供了渲染中间件，使用姿势如下：
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+// 注入 render 性能指标
+const renderTiming: MiddlewareHandler = async (c, next) => {
+  const start = Date.now();
+
+  await next();
+
+  const end = Date.now();
+  c.res.headers.set('server-timing', `render; dur=${end - start}`);
+};
+
+// 修改响应体
+const modifyResBody: MiddlewareHandler = async (c, next) => {
+  await next();
+
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
+
+  c.res = c.body(newText, {
+    status: res.status,
+    headers: res.headers,
+  });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [
+    {
+      name: 'render-timing',
+      handler: renderTiming,
+    },
+    {
+      name: 'modify-res-body',
+      handler: modifyResBody,
+    },
+  ],
+});
+```
+
+
+### Plugin
+
+Modern.js 支持在自定义插件中为 Server 添加上述 Middleware 及 RenderMiddleware，使用姿势如下：
+
+
+```ts title="server/plugins/server.ts"
+import type { ServerPluginLegacy } from '@modern-js/server-runtime';
+
+export default (): ServerPluginLegacy => ({
+  name: 'serverPlugin',
+  setup(api) {
+    return {
+      prepare(serverConfig) {
+        const { middlewares, renderMiddlewares } = api.useAppContext();
+
+        // 注入服务端数据，供页面 dataLoader 消费
+        middlewares?.push({
+          name: 'server-plugin-middleware',
+          handler: async (c, next) => {
+            c.set('message', 'hi modern.js');
+            await next();
+            // ...
+          },
+        });
+
+        // 重定向
+        renderMiddlewares?.push({
+          name: 'server-plugin-render-middleware',
+          handler: async (c, next) => {
+            const user = getUser(c.req);
+            if (!user) {
+              return c.redirect('/login');
+            }
+
+            await next();
+          },
+        });
+        return serverConfig;
+      },
+    };
+  },
+});
+```
+
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig } from '@modern-js/server-runtime';
+import serverPlugin from './plugins/serverPlugin';
+
+export default defineServerConfig({
+  plugins: [serverPlugin()],
+});
+```
+
+
+```ts title="src/routes/page.data.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+import { defer } from '@modern-js/runtime/router';
+
+export default () => {
+  const ctx = useHonoContext();
+  // SSR 场景消费服务端注入的数据
+  const message = ctx.get('message');
+
+  // ...
+};
+
+```
+
+
+## 旧版 API（废弃）
+
+:::warning
+旧版 API 兼容但不再推荐使用，扩展 Server 能力请移步 [自定义 Web Server](/guides/advanced-features/web-server.html)，迁移指南参考 [迁移至新版自定义 Web Server](/guides/advanced-features/web-server.html#迁移至新版自定义-web-server)。
+:::
+
+### 开启
+开启自定义 Web Server 功能，需要执行以下步骤：
+1. devDependencies 增加 `@modern-js/plugin-server`、`tsconfig-paths` 及 `ts-node`依赖并安装。
+2. `tsconfig` 的 `include` 中添加 `server`。
+3. `modern.config.ts` 中注册 `@modern-js/plugin-server` 插件。
+4. 项目目录下创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。
+
 
 ### Unstable Middleware
 
@@ -68,10 +269,6 @@ export const unstableMiddleware: UnstableMiddleware[] = [time];
 
 ### Hook
 
-:::warning
-我们推荐使用 UnstableMiddleware 代替 Hook。
-:::
-
 Modern.js 提供的 Hook 用于控制 Web Server 中的特定逻辑，所有的页面请求都会经过 Hook。
 
 目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，开发者可以在 `server/index.ts` 中这样写：
@@ -102,12 +299,12 @@ export const afterRender: AfterRenderHook = (ctx, next) => {
 :::
 
 
-## 迁移至新版自定义 Server
+## 迁移至新版自定义 Web Server
 
 ### 迁移背景
 
 Modern.js Server 在不断演进，为了提供更强大的功能，我们对中间件和 Server 插件的定义和使用方式进行了优化。
-虽然旧版自定义 Web Server 写法仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版的优势。
+虽然旧版 API 仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版的优势。
 
 ### 迁移步骤
 
@@ -152,7 +349,7 @@ UnstableMiddleware `Context` 和 Hono `Context` 的具体差异：
 | `c.request`              | `c.req.raw`                   | 参考 [HonoRequest raw](https://hono.dev/docs/api/request#raw) 文档         |
 | `c.response`             | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档       |
 | `c.route`                | `c.get('route')`              | 获取应用上下文信息                                                          |
-| `loaderContext.get`      | `honoContext.get`             | 通过 `c.set` 注入数据后 dataLoader 中消费：旧版通过 `loaderContext.get` 获取，新版参考 [Plugin](/guides/advanced-features/custom-server.html#使用姿势-2) 示例    |
+| `loaderContext.get`      | `honoContext.get`             | 通过 `c.set` 注入数据后 dataLoader 中消费：旧版通过 `loaderContext.get` 获取，新版参考 [Plugin](/guides/advanced-features/web-server.html#使用姿势-2) 示例    |
 
 #### Middleware
 

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

@@ -159,7 +159,7 @@ const getComplexStatistics = cache(
   }
 );
 
-revalidateTag('dashboard-stats'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
+revalidateTag('dashboard'); // 会使 getDashboardStats 函数和 getComplexStatistics 函数的缓存都失效
 ```
 
 #### `getKey` 参数

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

@@ -110,7 +110,6 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 
 :::info
 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
-
 :::
 
 在 Netlify 平台上添加项目，部署即可。
@@ -197,6 +196,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 ### 纯前端项目
 
 在当前项目的根目录添加 `vercel.json` 文件：
+
 ```bash
 ./
 ├── src
@@ -206,6 +206,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 ```
 
 在 `vercel.json` 中添加以下内容：
+
 ```json title="vercel.json"
 {
   "buildCommand": "modern deploy",
@@ -219,7 +220,6 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 
 :::info
 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
-
 :::
 
 ### 全栈项目
@@ -314,6 +314,7 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 4. 执行 `npm run deploy:gh-pages`。
 
 :::info
+
 1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
 2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 
@@ -393,7 +394,7 @@ Nginx 是一个高性能的 HTTP 和反向代理服务器，它可以处理静
 
 如果你的项目是纯前端项目，也可以通过 Nginx 来部署应用，以下提供一个 Nginx 配置的示例来演示如何托管一个纯前端项目的产物。
 
-```conf title="nginx.conf"
+```nginx title="nginx.conf"
 # user [user] [group];
 worker_processes 1;
 

package/docs/zh/guides/basic-features/output-files.mdx

@@ -96,34 +96,6 @@ dist
     └── qux.[hash].mp4
 ```
 
-## Node.js 产物目录
-
-当你在 Modern.js 中开启了 SSR 或 SSG 等服务端功能时，Modern.js 会在构建后生成一份 Node.js 产物，并输出到 `bundles` 目录下：
-
-```bash
-dist
-├── bundles
-│   └── [name].js
-├── static
-└── html
-```
-
-Node.js 产物通常只包含 JS 文件，不包含 HTML、CSS 等文件。此外，Node 产物的 JS 文件名称也不会自动生成哈希值。
-
-你可以通过 [output.distPath.server](/configure/app/output/dist-path) 配置项来修改 Node 产物的输出路径。
-
-比如，将 Node.js 产物输出到 `server` 目录：
-
-```ts
-export default {
-  output: {
-    distPath: {
-      server: 'server',
-    },
-  },
-};
-```
-
 ## 扁平化产物目录
 
 有时候你不想产物目录有太多层级，可以将目录设置为空字符串，使生成的产物目录扁平化。

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

@@ -222,7 +222,7 @@ document.addEventListener('load', () => {
 export const doSomething = () => {}
 ```
 
-如果直接引用到组件中，会造成 CSR 加载报错，即使你已经使用环境变量进行判断，但仍然无法移除依赖中副作用的执行。
+如果直接引用到组件中，会造成 SSR 加载报错，即使你已经使用环境变量进行判断，但仍然无法移除依赖中副作用的执行。
 
 ```tsx title="routes/page.tsx"
 import { doSomething } from 'packageA';

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

@@ -72,7 +72,7 @@ export const loader = ({ params }: LoaderFunctionArgs) => {
 另外，`defer` 还可以同时接收异步数据和同步数据。在下述例子中，我们等待部分耗时较短的请求，在响应后通过对象数据返回，而耗时较长时间的请求，则通过 Promise 返回：
 
 ```ts title="user/[id]/page.data.ts"
-export const loader = ({ params }: LoaderFunctionArgs) => {
+export const loader = async ({ params }: LoaderFunctionArgs) => {
   const userId = params.id;
 
   const user = new Promise<User>(resolve => {

package/docs/zh/guides/basic-features/static-assets/wasm-assets.mdx

@@ -12,7 +12,7 @@ WebAssembly（缩写为 wasm）是一种可移植、高性能的字节码格式
 
 ## 引用方式
 
-你可以直接在 JavaScript 文件中引用一个 WebAssembly 模块：
+你可以在 JavaScript 文件中使用 named import 引用一个 WebAssembly 模块：
 
 ```js title="index.js"
 import { add } from './add.wasm';

package/docs/zh/guides/topic-detail/module-federation/deploy.mdx

@@ -1,8 +1,17 @@
 # 部署
 
-通常情况下，部署 Module Federation 应用，需要在消费者上将远程模块地址，调整为其线上地址。
+通常情况下，部署 Module Federation 应用，需要注意两点：
 
-例如已经将生产者部署到 `https://my-remote-module` 这个域名下，可以这样修改消费者的 `module-federation.config.ts` 文件：
+1. 保证消费者配置文件中的远程模块地址无误，消费者能够正确访问到生产者的 `manifest` 文件。
+2. 保证生产者 `manifest` 文件中各个资源能被正确访问到。
+
+我们推荐使用 Modern.js 的 [Node 服务](/guides/basic-features/deploy.html#modernjs-内置-nodejs-服务器)来部署 Module Federation 应用，以获得开箱即用的体验。
+
+## 消费者
+
+对于 Module Federation 的消费者来说，它与生产者的联系就是在配置文件中的远程模块地址。
+
+例如生产者部署在 `https://my-remote-module` 这个域名下，开发者需要修改消费者的配置文件：
 
 ```ts title="module-federation.config.ts"
 import { createModuleFederationConfig } from '@module-federation/modern-js';
@@ -10,7 +19,7 @@ import { createModuleFederationConfig } from '@module-federation/modern-js';
 export default createModuleFederationConfig({
   name: 'host',
   remotes: {
-    remote: 'remote@http://my-remote-module/mf-manifest.json',
+    remote: 'remote@https://my-remote-module/static/mf-manifest.json',
   },
   shared: {
     react: { singleton: true },
@@ -19,10 +28,77 @@ export default createModuleFederationConfig({
 });
 ```
 
-此时，消费者将加载生产环境的 `remote` 模块的 `manifest` 配置文件。
+此时，消费者将加载远程模块生产环境的 `manifest` 配置文件。
+
+:::note
+上述代码中，远程模块的地址是 `/static/mf-manifest.json`，这只是以 Modern.js 默认的产物路径举例。在实际项目中，开发者需要根据实际的访问路径进行配置。
+:::
+
+## 生产者
+
+对于 Module Federation 的生产者，开发者需要正确的配置 [`output.assetPrefix`](/configure/app/output/asset-prefix) 配置，它会影响到：
+
+1. `mf-manifest.json` 中定义的 `publicPath`，它决定了远程模块其他资源的访问路径。
+2. 通过 Modern.js 服务直接托管产物时，`mf-manifest.json` 文件的访问路径。
+
+在生产环境，开发者需要将 `output.assetPrefix` 配置为生产环境的访问路径。例如我们将生产者部署在 `https://my-remote-module` 这个域名下，需要将 `output.assetPrefix` 配置为 `https://my-remote-module`。
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  output: {
+    assetPrefix: 'https://my-remote-module',
+  },
+});
+```
+
+此时，生产者构建产物 `mf-manifest.json` 中定义的 `publicPath` 为 `https://my-remote-module`，例如：
+
+```json
+{
+  "id": "remote",
+  "name": "remote",
+  "metaData": {
+    "name": "remote",
+    "publicPath": "https://my-remote-module/"
+  },
+  "shared": [ /* xxx */ ],
+  "remotes": [],
+  "exposes": [ /* xxx */ ]
+}
+```
+
+消费者在访问远程模块时，会自动将 `publicPath` 拼接在远程模块的资源路径前。
+
+该配置也会影响到生产者 `mf-manifest.json` 的访问路径。例如将这个值设置为 `MyDomain/module-a` 时，`mf-manifest.json` 的托管路径变为 `MyDomain/module-a/static/mf-manifest.json`。
+
+此时，消费者在配置远程模块时，需要配置以下地址：
+
+```ts title="module-federation.config.ts"
+import { createModuleFederationConfig } from '@module-federation/modern-js';
+
+export default createModuleFederationConfig({
+  name: 'host',
+  remotes: {
+    remote: 'remote@MyDomain/module-a/static/mf-manifest.json',
+  },
+});
+```
+
+## 本地验证部署
 
-## 通过平台部署
+Modern.js 提供了 `modern deploy` 命令，可以方便生成可运行在 Node.js 环境的产物。
 
-上述部署方式只是最简单的实践，在真实场景还有很多限制，例如版本管理、发布时序等。在字节跳动内部，我们在部署平台上搭建了 Module Federation 应用的部署流程，可以帮助开发者解决这些问题。
+```bash
+modern deploy
+```
+
+执行命令后，可以在控制台看到以下输出：
+
+```bash
+Static directory: .output/static
+You can preview this build by node .output/index
+```
 
-我们会持续关注社区里类似功能的平台，在未来完善 Modern.js + Module Federation 在这些类平台上的部署文档。
+此时，开发者只需要运行 `node .output/index` 即可在本地预览部署后的效果。无论是 CSR 应用或是 SSR 应用，所有的 Module Federation 产物都能够被正确的访问。

package/docs/zh/guides/topic-detail/module-federation/usage.mdx

@@ -189,8 +189,6 @@ export default Index;
 import { appTools, defineConfig } from '@modern-js/app-tools';
 import { moduleFederationPlugin } from '@module-federation/modern-js';
 
-const isLocal = process.env.IS_LOCAL === 'true';
-
 // https://modernjs.dev/en/configure/app/usage
 export default defineConfig({
   server: {
@@ -203,7 +201,7 @@ export default defineConfig({
     // Now this configuration is only used in the local when you run modern serve command.
     // If you want to deploy the application to the platform, use your own domain name.
     // Module federation will automatically write it to mf-manifest.json, which influences consumer to fetch remoteEntry.js.
-    assetPrefix: isLocal ? 'http://127.0.0.1:3051' : '/',
+    assetPrefix: 'http://127.0.0.1:3051',
   },
   plugins: [
     appTools({
@@ -214,7 +212,7 @@ export default defineConfig({
 });
 ```
 
-现在，在生产者中运行 `IS_LOCAL=true modern build && modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
+现在，在生产者中运行 `modern build && modern serve`，在消费者中运行 `modern build && modern serve`，即可在本地模拟生产环境，访问到远程模块。
 
 上述用例可以参考：[Modern.js & Module Federation 基础用法示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/module-federation/base)。
 

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

@@ -324,7 +324,7 @@ api.modifyWebpackConfig((config, utils) => {
 ```typescript
 api.modifyServerRoutes(routes => {
   // 添加一个新的 API 路由
-  routes.concat({
+  routes.push({
     urlPath: '/api',
     isApi: true,
     entryPath: '',

package/docs/zh/tutorials/first-app/c04-routes.mdx

@@ -118,8 +118,9 @@ import { Radio } from 'antd';
 
 然后将 UI 最顶部进行修改，增加一组单选框
 
-```tsx {4-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   return (
     <div>
       <div className="h-16 p-2 flex items-center justify-center">
@@ -146,8 +147,9 @@ import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
 
 最后在 Layout 组件里增加局部状态和相关逻辑：
 
-```tsx {2-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   const navigate = useNavigate();
   const location = useLocation();
   const [currentList, setList] = useState(location.pathname || '/');

package/docs/zh/tutorials/first-app/c05-loader.mdx

@@ -56,11 +56,13 @@ Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以
 
 Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
 
-```tsx {1,2,5,13}
+```tsx
+// [!code highlight:2]
 import { useLoaderData } from '@modern-js/runtime/router';
 import type { LoaderData } from './page.data';
 
 function Index() {
+  // [!code highlight:1]
   const { data } = useLoaderData() as LoaderData;
 
   return (
@@ -68,6 +70,7 @@ function Index() {
       <Helmet>
         <title>All</title>
       </Helmet>
+      // [!code highlight:1]
       <List
         dataSource={data}
         renderItem={info => <Item key={info.name} info={info} />}