@modern-js/main-doc 2.0.0-beta.4 → 2.0.0-beta.5

package/zh/guides/basic-features/data-fetch.md

@@ -5,7 +5,404 @@ sidebar_position: 3
 
 Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。
 
-需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好的管理数据与路由的关系。
+需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好地管理数据，提升项目的性能。
+
+## Data Loader(推荐)
+
+Modern.js 推荐使用约定式路由做路由的管理，通过 Modern.js 的[约定式（嵌套）路由](/docs/guides/basic-features/routes#约定式路由)，每个路由组件(`layout.ts` 或 `page.ts`)可以导出一个函数`loader`，该函数可以在组件渲染之前，为路由组件提供数据。
+
+:::info
+Modern.js 旧版支持通过 [useLoader](#useloader旧版) 获取数据，这已经不是我们推荐的用法，除迁移过程外，不推荐两者混用。
+:::
+
+### 基础示例
+
+每个路由组件可以导出一个 `loader` 函数，然后通过 `useLoaderData` 函数获得相应的数据:
+
+```ts
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+在 CSR 环境下，`loader` 函数会在客户端执行，`loader` 函数内可以使用浏览器的 API（但通常不需要，也不推荐）。
+
+在 SSR 环境下，不管是首屏，还是在客户端的导航，`loader` 函数只会在服务端执行，这里可以调用任意的 Node.js API，同时这里使用的任何依赖和代码都不会包含在客户端的 bundle 中。
+
+:::info
+在以后的版本中，Modern.js 可能会支持在 CSR 环境下，`loader` 函数也在服务端运行，以提高性能和安全性，所以这里建议尽可能地保证 loader 的纯粹，只做数据获取的场景。
+:::
+
+当在客户端导航时，基于 Modern.js 的[约定式路由](/docs/guides/basic-features/routes)，所有的 loader 函数会并行执行（请求），即当访问 `/user/profile` 时，`/user` 和 `/user/profile` 下的 loader 函数都会并行执行（请求），以提高客户端的性能。
+
+### Loader 放在单独文件中
+
+除了支持 `loader` 函数从前端组件中导出，Modern.js 也支持将 `loader` 函数放在单独的文件中， 将 `loader` 函数放在单独的文件中，可以无需留意[副作用](#副作用处理)相关注意事项，但可以要注意的是，路由组件如 `layout.ts` 和 loader 文件 `layout.loader.ts` 不能引入彼此的代码，如果需要相关类型可以使用 `import type`，可以见下面的示例：
+
+```
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        ├── layout.loader.ts
+        ├── page.tsx
+        └── page.loader.ts
+```
+
+如[基础示例](#基础示例)中的 `loader` 可以用以下代码替代：
+```tsx
+// routes/user/page.loader.tsx
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  return await res.json();
+}
+
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+// 这里只能使用 import type，导入类型
+import type { ProfileData } from './page.loader';
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+
+### `loader` 函数
+
+
+`loader` 函数有两个入参：
+##### `Params`
+
+当路由文件通过 `[]` 时，会作为[动态路由](/docs/guides/basic-features/routes#动态路由)，动态路由片段会作为参数传入 loader 函数：
+
+```tsx
+// routes/user/[id]/page.tsx
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export const loader = async({ params }: LoaderArgs) => {
+  const { id } = params;
+  const res = await fetch(`https://api/user/${id}`);
+  return res.json();
+}
+```
+
+当访问 `/user/123` 时，`loader` 函数的参数为 `{ params: { id: '123' } }`。
+
+##### `request`
+
+request 是一个 [Fetch Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) 实例。
+
+一个常见的使用场景是通过 `request` 获取查询参数：
+```tsx
+// routes/user/[id]/page.tsx
+import { LoaderArgs } from '@modern-js/runtime/router';
+
+export const loader = async({ request }: LoaderArgs) => {
+  const url = new URL(request.url);
+  const userId = url.searchParams.get("id");
+  return queryUser(userId);
+}
+```
+
+#### 返回值
+
+`loader` 函数的返回值可以是任何可序列化的内容，也可以是一个 [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) 实例：
+
+```tsx
+export const loader = async(): ProfileData => {
+  return {
+    message: 'hello world',
+  }
+}
+```
+
+默认情况下，`loader` 返回的响应 `Content-type` 是 `application/json`，`status` 为 200，你可以通过自定义 `Response` 来设置：
+```tsx
+export const loader = async(): ProfileData => {
+  const data = {message: 'hello world'};
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json; utf-8",
+    },
+  });
+}
+```
+
+### 请求 API
+
+Modern.js 对 `fetch` API 做了 polyfill, 用于发起请求，该 API 与浏览器的 `fetch` API 一致，但是在服务端也能使用该 API 发起请求，这意味着不管是 CSR 还是 SSR，都可以使用统一的 `fetch` API 进行数据获取：
+```tsx
+export async function loader(){
+  const res = await fetch('https://api/user/profile');
+}
+```
+
+
+### 错误处理
+
+在 `loader` 函数中，可以通过 `throw error` 或者 `throw response` 的方式处理错误，当 `loader` 函数中有错误被抛出时，Modern.js 会停止执行当前 loader 中的代码，并将前端 UI 切换到定义的 [`ErrorBoundary`](/docs/guides/basic-features/routes#错误处理) 组件：
+```tsx
+// routes/user/profile/page.tsx
+export async function loader(){
+  const res = await fetch('https://api/user/profile');
+  if(!res.ok){
+    throw res;
+  }
+  return res.json();
+}
+
+// routes/user/profile/error.tsx
+import { useRouteError } from '@modern-js/runtime/router';
+const ErrorBoundary = () => {
+  const error = useRouteError() as Response;
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.statusText}</h2>
+    </div>
+  );
+};
+
+export default ErrorBoundary;
+```
+
+### 获取上层组件数据
+
+很多场景下，子组件需要获取到祖先组件 loader 中的数据，你可以通过 `useRouteLoaderData` 方便地获取到祖先组件的数据：
+```tsx
+// routes/user/profile/page.tsx
+import { useRouteLoaderData } from '@modern-js/runtime/router';
+
+export default function UserLayout() {
+  // 获取 routes/user/layout.tsx 中 loader 返回的数据
+  const data = useRouteLoaderData('user/layout');
+  return (
+    <div>
+      <h1>{data.name}</h1>
+      <h2>{data.age}</h2>
+    </div>
+  );
+}
+```
+
+`userRouteLoaderData` 接受一个参数 `routeId`，在使用约定式路由时，Modern.js 会为你自动生成`routeId`，`routeId` 的值是对应组件相对于 `src/routes` 的路径，如上面的例子中，子组件想要获取 `routes/user/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `user/layout`。
+
+在多 entry（MPA） 场景下，`routeId` 的值需要加上对应 entry 的 name，entry name 非指定情况下一般是 entry 目录名，如以下目录结构：
+```bash
+.
+└── src
+    ├── entry1
+    │   ├── layout.tsx
+    └── entry2
+        └── layout.tsx
+```
+
+如果想获取 `entry1/layout.tsx` 中 loader 返回的数据，`routeId` 的值就是 `entry1_layout`。
+
+
+### (WIP)Loading UI
+
+:::info
+此功能目前是实验性质，后续 API 可能有调整。
+目前仅支持 CSR，敬请期待 Streaming SSR。
+:::
+
+因为获取数据是异步的，在数据获取完成之前，常常需要展示一个 Loading UI，以下是一个基本的示例，假设有以下目录：
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+我们在 `user/layout.tsx` 中获取用户的详细数据，在获取数据之前，希望展示一个 Loading UI。
+
+首先，在项目中在 `routes` 目录下增加一个 `loading.tsx` 组件，该 `loading` 组件会对子目录下的所有路由生效（如 user）：
+```bash
+.
+└── routes
+    ├── layout.tsx
+    └── user
+        ├── layout.tsx
+        └── page.ts
+```
+
+:::info
+loading 组件的具体用法，请查看[loading](/docs/guides/basic-features/routes#loading)
+:::
+
+然后，在 `user/layout.tsx` 中添加以下代码：
+```tsx title="routes/user/layout.tsx"
+import {
+  Await,
+  defer,
+  useLoaderData,
+  Outlet
+} from '@modern-js/runtime/router';
+
+export const loader = () => {
+  return defer({
+    // fetchUserInfo 是一个异步函数，返回用户信息
+    userInfo: fetchUserInfo(),
+  })
+}
+
+export default function UserLayout() {
+  const { userInfo } = useLoaderData() as {userInfo: Promise<UserInfo>};
+  return (
+    <div>
+      <Await resolve={userInfo} children={userInfo => (
+        <div>
+          <span>{userInfo.name}</span>
+          <span>{userInfo.age}</span>
+          <Outlet>
+        </div>
+      )}>
+      </Await>
+    </div>
+  );
+}
+```
+
+:::info
+Await 组件的具体用法请查看 [Await](https://reactrouter.com/en/main/components/await)
+
+defer 的具体用法请查看 [defer](https://reactrouter.com/en/main/guides/deferred)
+:::
+
+
+<!-- TODO 缓存相关 -->
+
+### 副作用处理
+
+如上面所述，Modern.js 会将服务端代码 `loader` 从客户端 bundle 中移除，有一些你需要注意的事项，如果不想受副作用的影响，可以使用[单独文件](#单独文件) 的方式定义 `loader`。
+
+:::info
+在 CSR 场景下，通常副作用对项目影响较小，但依然希望你能遵循以下约定。
+:::
+
+模块的副作用可以认为是在模块被加载时执行的代码，比如：
+```tsx
+// routes/user/page.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+// highlight-next-line
+import { transformProfile } from "./utils";
+// highlight-next-line
+console.log(transformProfile);
+
+export const loader = async(): ProfileData => {
+  const res = await fetch('https://api/user/profile');
+  const data = await res.json();
+  return transformProfile(data);
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+```
+
+因为 `console.log` 在 `routes/user/page.tsx` 加载时，就会被执行，编译器不会移除它，`transformProfile` 就会打包到客户端的 bundle 中。
+
+所以我们不推荐有任何代码在模块加载时执行，包括项目代码和使用的第三方模块，以下是一些我们不推荐的写法：
+
+```tsx
+// routes/user/page.tsx
+export default function UserPage() {
+  return <div>profile</div>;
+}
+
+UserPage.config = {}
+```
+
+```tsx
+// routes/init.ts
+document.title = 'Modern.js';
+
+// routes/layout.tsx
+import "./init.ts";
+
+export default function Layout() {
+  return <></>
+}
+```
+
+在 SSR 场景，通常你需要在 `loader` 函数中使用 Node.js 核心包和依赖，对于非 Node.js 核心包，需要使用一个特殊约定的文件做重新导出，如使用 `fs-extra`：
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```
+
+
+### 错误用法
+
+1. `loader` 中只能返回可序列化的数据，在 SSR 环境下，`loader` 函数的返回值会被序列化为 JSON 字符串，然后在客户端被反序列化为对象。因此，`loader` 函数中不能返回不可序列化的数据（如函数）。
+
+:::warning
+目前 CSR 下没有这个限制，但我们强烈推荐你遵循该限制，且未来我们可能在 CSR 下也加上该限制。
+:::
+
+```ts
+// This won't work!
+export const loader = () => {
+  return {
+    user: {},
+    method: () => {
+
+    }
+  }
+}
+```
+
+2. Modern.js 会帮你调用 `loader` 函数，你不应该自己调用 `loader` 函数：
+```ts
+// This won't work!
+export const loader = async () => {
+  const res = fetch('https://api/user/profile');
+  return res.json();
+};
+
+export default function RouteComp() {
+  const data = loader();
+}
+```
+
+3. 在服务端运行时，`loader` 函数会被打包为一个统一的 bundle，所以我们不推荐服务端的代码使用 `__filename` 和 `__dirname`。
+
 
 ## useLoader（旧版）
 
@@ -58,8 +455,4 @@ Modern.js 在新版本中，设计了全新的 Loader 方案。新方案解决
 :::note
 详细 API 可以查看 [useLoader](/docs/apis/app/runtime/core/use-loader)。
 :::
-## Route Loader
 
-:::note
-敬请期待
-:::

package/zh/guides/basic-features/routes.md

@@ -177,7 +177,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 `routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
 
-当路由目录下存在该组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。当该目录下未定义 `layout.tsx` 文件时，`<Loading>` 组件不会生效。例如以下文件目录：
+当路由目录下存在该组件和 `layout` 组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。例如以下文件目录：
 
 ```bash
 .
@@ -191,7 +191,38 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
     └── page.tsx
 ```
 
-当路由从 `/` 跳转到 `/blog` 时，如果 `<Blog>` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。但从 `/blog` 跳转到 `/blog/20220101` 时，则不会展示。
+当定义 `loading.tsx` 时，就相当于以下布局：
+```tsx title="当路由为 / 时"
+<Layout>
+  <Suspense fallback={<Loading/>}>
+    <Page><Page>
+  </Suspense>
+</Layout>
+```
+
+```tsx title="当路由为 /blog 时"
+<Layout>
+  <Suspense fallback={<Loading/>}>
+    <BlogPage />
+  </Suspense>
+</Layout>
+```
+
+```tsx title="当路由为 /blog/123 时"
+<Layout>
+  <Suspense fallback={<Loading/>}>
+    <BlogIdPage />
+  </Suspense>
+</Layout>
+```
+:::info
+当目录的 layout 组件不存在时，该目录下的 loading 组件也不会生效。
+:::
+
+当路由从 `/` 跳转到 `/blog` 时，如果 `blog/page` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。
+
+同理，当路由从 `/` 或者 `/blog` 跳转到 `/blog/123` 时，如果 `blog/[id]/page` 组件的 JS Chunk 还未加载，也会先展示 `loading.tsx` 中导出的组件 UI。
+
 
 ### 错误处理
 
@@ -206,7 +237,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 ```tsx
 import { useRouteError } from '@modern-js/runtime/router';
-export default const ErrorBoundary = () => {
+const ErrorBoundary = () => {
   const error = useRouteError();
   return (
     <div>
@@ -215,6 +246,7 @@ export default const ErrorBoundary = () => {
     </div>
   )
 }
+export default ErrorBoundary;
 ```
 
 ## 自控式路由

package/zh/guides/concept/entries.md

@@ -3,7 +3,7 @@ title: 入口
 sidebar_position: 2
 ---
 
-入口是 Modern.js 默认的文件约定，项目的每一个入口是一张独立的页面，对应一条服务端路由。
+入口是 Modern.js 默认的文件约定，项目的每一个入口是一张独立的页面，对应一条**服务端路由**。
 
 很多配置，如 HTML 模板、Meta 信息、是否开启 SSR、SSG、服务端路由规则都是以入口为维度划分的。
 
@@ -56,10 +56,13 @@ Modern.js 可以很方便的将单入口切换成多入口。可以在项目下
 执行 `pnpm run dev` 后，可以看到新增一条 `/new-entry` 的路由，并且被迁移的代码路由并未发生变化。
 
 :::note
-Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，默认路由为 `/`，其他入口默认路由为 `/{entryName}`。
+Modern.js 会将和 `package.json` 中 `name` 字段同名的入口作为主入口，默认路由为 `/`，其他入口默认路由为 `/{entryName}`。
 :::
 
-## 入口条件
+
+## 入口类型
+
+不同的入口类型具有不同的编译和运行时行为。在 Modern.js 创建项目时，开发者可以手动选择创建**框架模式**或是**构建模式**的项目。完成创建后，可以看到不同模式的项目样板文件是不同的。
 
 默认情况下，Modern.js 启动项目前会对 `src/` 下的文件进行扫描，识别入口，并生成对应的服务端路由。
 
@@ -82,34 +85,121 @@ Modern.js 会将和 `package.json` 中 `name` 同名的目录作为主入口，
 
 当项目不是单入口应用时，Modern.js 会进一步查看 `src/` 下的一级目录。
 
-## 入口的区别
+### 框架模式入口
 
-不同约定的入口具有不同的行为。
+框架模式指需要使用 Modern.js 框架能力，例如 Router、SSR、一体化调用等。这类入口约定下，开发者定义的入口并不是真正的 Webpack 编译入口。Modern.js 在启动时会生成一个封装过的入口，可以在 `node_modules/.modern/{entryName}/index.js` 找到真正的入口。
 
-### routes 入口
+#### 约定式路由
 
-如果入口为 `routes/` 约定，Modern.js 会在启动时扫描 `routes` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
+如果入口中存在 `routes/` 目录，Modern.js 会在启动时扫描 `routes/` 下的文件，基于文件约定，自动生成客户端路由（react-router）。
 
 详细内容可以参考[路由](/docs/guides/basic-features/routes)。
 
-### App 入口
+#### 自定义路由
 
-如果入口为 `App.[jt]sx?` 约定，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
+如果入口中存在 `App.[jt]sx?` 文件，开发者可以在这个文件中自由的设置客户端路由，或者不设置客户端路由。
 
 详细内容可以参考[路由](/docs/guides/basic-features/routes)。
 
-### Index 入口
+#### 自定义 App
+
+如果入口中存在 `index.[jt]sx` 文件，并且当文件默认导出函数时，Modern.js 还是会根据 runtime 的设置情况生成 createApp 包裹后的代码。在渲染过程中，将 createApp 包裹后的组件作为参数传递给 index 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```tsx
+import ReactDOM from 'react-dom/client'
+import { bootstrap } from '@modern-js/runtime';
+
+
+export default (App: React.ComponentType) => {
+  // do something before bootstrap...
+  bootstrap(App, 'root', undefined, ReactDOM);
+};
+```
+
+:::warning
+由于 bootstrap 函数需要兼容 React17 和 React18 的用法，调用 bootstrap 函数时需要手动传入 ReactDOM 参数。
+:::
+
+Modern.js 生成的文件内容如下：
+
+```js
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import customBootstrap from '@_edenx_src/index.tsx';
+import App from '@_edenx_src/App';
+import { router, state } from '@edenx/runtime/plugins';
+
+const IS_BROWSER = typeof window !== 'undefined' && window.name !== 'nodejs';
+const MOUNT_ID = 'root';
+
+let AppWrapper = null;
+
+function render() {
+  AppWrapper = createApp({
+    // runtime 的插件参数...
+  })(App)
+  if (IS_BROWSER) {
+    customBootstrap(AppWrapper);
+  }
+  return AppWrapper
+}
+
+AppWrapper = render();
+
+export default AppWrapper;;
+```
+
+### 构建模式入口
+
+构建模式是指不使用任何 Modern.js 运行时的能力，完全由开发者自己定义项目 Webpack 的入口。
+
+如果入口中存在 `index.[jt]sx` ，并且没有默认导出函数时，这时候该文件就是真正的 Webpack 入口文件。这里和 [Create React App](https://github.com/facebook/create-react-app) 类似，需要自己将组件挂载到 DOM 节点、添加热更新代码等。例如:
 
-通常情况下，上面两种模式已经能满足需求，但当开发者需要自己接管 React 挂载逻辑，或完全接管 Webpack 入口时，可以使用 `index.[jt]sx?` 约定。
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
 
-如果入口为 `index.[jt]sx?` 约定，Modern.js 会根据该文件是否存在默认的组件导出，来决定构建行为。
+ReactDOM.render(<App />, document.getElementById('root'));
+```
+
+Modern.js **不推荐**使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。但是在项目从其他框架迁移到 Modern.js，例如 CRA，或是自己手动搭建的 webpack 时，这种方式会非常有用。
 
-详细内容可以参考[自定义 App](/docs/guides/advanced-features/custom-app)。
+## 使用配置文件定义入口
 
-## 配置入口
+有些时候，已有的项目并不是按照 Modern.js 的目录结构来搭建的。如果强行要按照这种结构来工作，会有比较大的迁移成本。
 
 在 Modern.js 中，除了使用文件约定生成入口外，还可以在 `modern.config.[jt]s` 中手动配置入口。
 
+```ts
+export default defineConfig({
+  source: {
+    entries: {
+      // 指定一个名称为 entry_customize 的新入口
+      entry_customize: './src/home/test/index.js',
+    },
+  },
+});
+```
+
 :::tip
 详情可以查看 [source.entries](/docs/configure/app/source/entries)。
 :::
+
+## 禁用默认入口扫描
+
+另外，项目的部分结构可能恰巧命中了 Modern.js 的约定，但实际上这部分并不是真实的入口。
+
+Modern.js 提供了配置，来禁用默认的入口扫描。与配置的入口结合使用，大部分项目可以在不修改目录结构的情况下，快速的进行迁移。
+
+```ts
+export default defineConfig({
+  source: {
+    disableDefaultEntries: true,
+  },
+});
+```
+
+:::tip
+详情可以查看 [source.disableDefaultEntries](/docs/configure/app/source/disable-default-entries)。
+:::

package/zh/guides/get-started/quick-start.md

@@ -46,7 +46,7 @@ import DebugApp from '@site-docs/components/debug-app.md'
 可以通过配置文件来开启功能，或覆盖 Modern.js 的默认行为。例如添加如下配置，开启 SSR：
 
 ```ts
-import { defineConfig } from '@modern-js/app-tools';
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
 
 // https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
@@ -57,6 +57,7 @@ export default defineConfig({
   server: {
     ssr: true,
   },
+  plugins: [AppToolsPlugin()],
 });
 ```
 
@@ -108,12 +109,12 @@ info    File sizes after production build:
 
 ## 本地验证
 
-在项目中执行 `pnpm run start` 即可在本地验证构建产物是否正常运行：
+在项目中执行 `pnpm run serve` 即可在本地验证构建产物是否正常运行：
 
 ```bash
-$ pnpm run start
+$ pnpm run serve
 
-> modern start
+> modern serve
 
 Starting the modern server...
 info    App running at:
@@ -127,4 +128,6 @@ info    App running at:
 
 ## 部署
 
-本地验证完成后，可以将 `dist/` 下的产物整理成服务器需要的结构，进行部署。
+import Deploy from '@site-docs/components/deploy.md'
+
+<Deploy />

package/zh/guides/get-started/upgrade.md

@@ -25,7 +25,9 @@ $ pnpm run upgrade
 
 Modern.js 所有的官方包目前都使用**统一版本号**进行发布。
 
-根据官网 Release Note，开发者也可以手动将项目升级到想要的版本。
+import ReleaseNote from '@site-docs/components/release-note.md'
+
+<ReleaseNote />
 
 :::tip
 当升级时，需要对 Modern.js 官方提供的所有包做统一升级，而不是升级单个依赖。