@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.3

package/zh/guides/advanced-features/ssg.md

@@ -1,5 +1,5 @@
 ---
-title: 静态站点生成
+title: 静态站点生成（SSG）
 sidebar_position: 4
 ---
 
@@ -9,11 +9,11 @@ SSG（Static Site Generation）是一种基于数据与模板，在构建时渲
 SSG 是构建阶段的解决方案，因此仅对生产环境有效。通过 `dev` 命令运行时，表现效果与 SSR 相同。
 :::
 
-我们首先需要执行`pnpm run new`启用 SSG 功能：
+我们首先需要执行 `pnpm run new` 启用 SSG 功能：
 
 ```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「SSG」功能
+? 请选择你想要的操作： 启用可选功能
+? 启用可选功能： 启用「SSG」功能
 ```
 
 SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
@@ -25,22 +25,37 @@ SSG 在**约定式路由**和**自控式路由**下的使用方式不同。
 例如，以下是一个使用约定式路由的项目目录结构：
 
 ```
-├── src/
-│   ├── pages/
-│   │   ├── home.tsx
-│   │   ├── info.tsx
-│   │   └── index.tsx
+.
+├── src
+│   └── routes
+│       ├── layout.tsx
+│       ├── page.tsx
+│       └── user
+│           ├── layout.tsx
+│           ├── page.tsx
+│           └── profile
+│               └── page.tsx
 ```
 
-在 `src/pages/index.tsx` 中添加组件代码：
+上述文件目录将会生成以下三条路由：
+
+- `/`
+- `/user`
+- `/user/profile`
+
+:::note
+如果还不了解约定式路由的规则，可以先查看[路由](/docs/guides/basic-features/routes)。
+:::
+
+在 `src/routes/page.tsx` 中添加组件代码：
 
 ```jsx title="src/pages/index.tsx"
 export default () => {
-  return  <div>index page</div>
+  return  <div>Index Page</div>
 }
 ```
 
-SSG 和 SSR 一样，也是在 Node.js 环境中完成页面渲染，因此我们可以在开发阶段开启 SSR，提前在开发阶段验证 SSG 渲染效果：
+SSG 也是在 Node.js 环境渲染页面，因此我们可以在**开发阶段开启 SSR**，提前在暴露代码问题，验证 SSG 渲染效果：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({
@@ -50,13 +65,11 @@ export default defineConfig({
 }
 ```
 
-在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件：
-
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-dev.png)
+在项目根路径下执行 `pnpm run dev` 命令，查看 `dist/` 目录，此时只生成一个 HTML 文件 `main/index.html`。
 
-在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/home/index.html` 和 `main/info/index.html` 3 个 HTML 文件，分别对应 `/`、`/home`、`/info` 3 个约定式路由，可见**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `index page` 的文本内容，这正是 SSG 的效果。
+在项目根路径下执行 `pnpm run build` 命令，构建完成后，查看 `dist/` 目录，此时生成 `main/index.html`、`main/user/index.html` 和 `main/user/profile/index.html` 三个 HTML 文件，内容分别对应上述三条路由。
 
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-build.png)
+**约定式路由**中的每一条路由，都会生成一个单独的 HTML 文件。查看 `main/index.html`，可以发现包含 `Index Page` 的文本内容，这正是 SSG 的效果。
 
 执行 `pnpm run start` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
 
@@ -64,45 +77,46 @@ export default defineConfig({
 
 **自控式路由**是通过组件代码自定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。此时需要用户提前告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
 
-例如有以下代码：
-
-```ts
-import { Switch, Route } from '@modern-js/runtime/router';
-
-export default () => (
-  <Switch>
-    <Route path="/" exact={true}>
-      <div>Home</div>
-    </Route>
-    <Route path="/foo" exact={true}>
-      <div>Foo</div>
-    </Route>
-  </Switch>
-);
-```
+例如有以下代码，包含多条路由，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`：
+
+```tsx title="src/App.tsx"
+import { useRuntimeContext } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
 
-希望为 `/foo` 路由开启 SSG 功能，同样利用 `output.ssg` 配置。该参数允许配置页面信息，告知 Modern.js 开启指定路由的 SSG 功能。
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const { context } = useRuntimeContext();
+  return (
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```
 
-例如上述入口中，包含两条客户端路由，分别是 `/` 和 `/foo`，设置 `output.ssg` 为 `true` 时，默认只会渲染入口路由即 `/`。如果我们希望同时开启 `/foo` 的 SSG 功能，可以这样配置：
+如果我们希望同时开启 `/about` 的 SSG 功能，可以配置 `output.ssg`，告知 Modern.js 开启指定路由的 SSG 功能。
 
 ```typescript title="modern.config.ts"
 export default defineConfig({
   output: {
     ssg: {
-      routes: ['/', '/foo'],
+      routes: ['/', '/about'],
     },
   },
 })
 ```
 
-执行 `pnpm run build` 与 `pnpm run start` 后，访问 `http://localhost:8080/foo`，在 Preview 视图中可以看到页面已经完成渲染。
-
-查看构建产物文件，可以看到 `dist/` 目录中，在默认的 `main` 入口产物目录下，新增一个 `foo.html` 文件：
+执行 `pnpm run build` 与 `pnpm run start` 后，访问 `http://localhost:8080/about`，在 Preview 视图中可以看到页面已经完成渲染。
 
-![vsc-alert](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ssg-foo.png)
+查看构建产物文件，可以看到 `dist/` 目录中，新增了一个 `main/about/index.html` 文件。
 
 :::info
-以上仅介绍了单入口的情况，与部分配置。更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
+以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/docs/configure/app/output/ssg)。
 :::
 
 ### 获取数据
@@ -116,36 +130,33 @@ export default defineConfig({
 - 在开发阶段，不管 `useLoader` 是否配置 `{ static: true }`，函数都会在 SSR 时获取数据。
 :::
 
-修改上述 `App.ts` 的代码为：
+修改上述 `src/App.ts` 的代码为：
 
-```ts title="App.ts"
-import { Switch, Route } from '@modern-js/runtime/router';
-import { useLoader } from '@modern-js/runtime';
+```tsx title="App.ts"
+import { useRuntimeContext, useStaticLoader } from '@modern-js/runtime';
+import { Routes, Route, BrowserRouter } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
 
 export default () => {
-  const { data } = useLoader(
-    async () => ({
-      message: Math.random(),
-    }),
-    {
-      static: true,
-      params: 'foo',
-    },
-  );
+  const { context } = useRuntimeContext();
+
+  const { data } = useStaticLoader(async () => ({
+    message: Math.random(),
+  }));
 
   return (
-    <Switch>
-      <Route path="/" exact={true}>
-        <div>Home</div>
-      </Route>
-      <Route path="/foo" exact={true}>
-        <div>Foo, {data?.message}</div>
-      </Route>
-    </Switch>
+    <Router location={context.request.pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about, {data?.message}</div>} />
+      </Routes>
+    </Router>
   );
 };
 ```
 
 执行 `pnpm run dev`，重复刷新页面，可以看到 `/foo` 页面的渲染结果不断发生变化，说明数据是在请求时获取的。
 
-重新执行 `pnpm run build` 后，执行 `pnpm run start`，重复刷新页面，发现页面渲染结果始终保持同样的内容，说明数据在请求时不会再次获取。
+重新执行 `pnpm run build` 后，执行 `pnpm run start`，重复刷新页面，发现页面渲染结果始终保持同样的内容，数据在请求时不会再次获取，说明页面在编译时已经完成渲染。

package/zh/guides/advanced-features/ssr.md

@@ -1,11 +1,11 @@
 ---
-title: 服务端渲染
+title: 服务端渲染（SSR）
 sidebar_position: 3
 ---
 
-在 Modern.js 中，和 Web Server 一样，SSR 服务与应用也是一体的，开发者无需为 SSR 编写复杂的服务端逻辑。同样，开发者也无需关心 SSR 服务的运维，Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
+在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。Modern.js 拥有完备的 SSR 降级策略，保证页面能够安全运行。
 
-Modern.js 启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configure/app/server/ssr) 为 `true` 即可：
+启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configure/app/server/ssr) 为 `true` 即可：
 
 ```json title="package.json"
 {
@@ -15,9 +15,9 @@ Modern.js 启用 SSR 非常简单，只需要设置 [`server.ssr`](/docs/configu
 }
 ```
 
-## SSR 时的数据请求
+## SSR 时的数据获取
 
-Modern.js 中提供了 `useLoader` Hooks API，可以在某些场景下代替 `useEffect` 进行数据请求。这是一个同构的 API，直接使用它即可完成在服务端的数据获取：
+Modern.js 中提供了 [`useLoader`](/docs/apis/app/runtime/core/use-loader) Hooks API，用于在 SSR 环境下同构的获取数据：
 
 ```ts
 const { data, loading, error } = useLoader(() => {
@@ -30,16 +30,14 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 不过，开发者仍然需要关注数据的兜底处理，例如 `null` 值或不符合预期的数据返回。避免在 SSR 时产生 React 渲染错误或是返回凌乱的渲染结果。
 
 :::info 补充信息
-关于 `useLoader` 的详细介绍可以参考[这里](/docs/apis/app/runtime/core/use-loader)。
+更多相关内容可以查看[数据获取](/docs/guides/basic-features/data-fetch)。
 :::
 
 ## 保持渲染一致
 
-代码中区分 SSR 和 CSR 渲染，通常需要根据当前的运行容器环境特征做判断，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息或是某个 Native 模块。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
+有些业务中，通常需要根据当前的运行容器环境特征做不同的 UI 展示，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。如果处理不够仔细，此时很有可能出现不符合预期的渲染结果。
 
-这里通过一个例子，演示当 SSR 与 CSR 渲染不一致时出现的问题。
-
-在组件中添加以下代码：
+这里通过一个例子，演示当 SSR 与 CSR 渲染不一致时出现的问题，在组件中添加以下代码：
 
 ```tsx
 {
@@ -57,7 +55,7 @@ Modern.js 打破传统的 SSR 开发模式，提供了用户无感的 SSR 开发
 Warning: Expected server HTML to contain a matching <div> in <div>.
 ```
 
-这是因为 React 在客户端执行注水逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
+这是 React 在客户端执行注水逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
 :::info 注
 关于注水逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
@@ -184,3 +182,68 @@ import { PreRender } from '@modern-js/runtime/ssr';
 :::info 补充信息
 `PreRender` 的详细使用可以参考[这里](/docs/apis/app/runtime/ssr/pre-render)。
 :::
+
+## Treeshaking
+
+开启 SSR 时，Modern.js 会用相同的入口，构建出 SSR Bundle 和 CSR Bundle 两份产物。因此，在 SSR Bundle 中存在 Web API，或是在 CSR Bundle 中存在 Node API 时，都可能导致运行出错。
+
+### 环境变量区分
+
+在组件中可以直接使用 Modern.js 内置的环境变量 `MODERN_TARGET` 进行判断，方便在构建时删除无用代码：
+
+```ts
+export default () => {
+  if (process.env.MODERN_TARGET === 'node') {
+    console.log('server render');
+  } else {
+    console.log('client render');
+  }
+}
+```
+
+:::note
+更多内容可以查看[环境变量](/docs/guides/basic-features/env-vars)。
+:::
+
+### 文件后缀区分
+
+但有时，这种 Treeshaking 的方式并不能保证代码被完全分离。EdenX 也支持通过 `.node.` 后缀的文件来区分 SSR Bundle 和 CSR Bundle 产物的打包文件。
+
+例如存在 `client-sdk` 中直接使用了 Web API：
+
+```ts
+// client-sdk
+export const href = location.href;
+```
+
+这时候直接引用到组件中，会造成 SSR 报错。可以创建同名的 `.ts` 和 `.node.ts` 文件做一层代理：
+
+```ts title="compat.ts"
+export { href } from 'client-sdk';
+```
+
+```ts title="compat.node.ts"
+export const href = '';
+```
+
+在文件中直接引入 `./compat`，此时 SSR 环境下会优先使用 `.node.ts` 后缀的文件，CSR 环境下会使用 `.ts` 后缀的文件。
+
+```ts title="App.tsx"
+import { href } from './compat'
+
+export default () => {
+  return <div onClick={() => { console.log(href) }}></div>
+}
+```
+
+### 独立文件
+
+上述两种方式，都会为开发者带来一些心智负担。Modern.js 正在基于[嵌套路由](/docs/guides/basic-features/routes)开发设计[更简单的方案](/docs/guides/basic-features/data-fetch)来分离 CSR 和 SSR 的代码。
+
+## 接口请求
+
+在 SSR 中发起接口请求时，开发者有时自己封装了同构的请求工具。部分接口需要传递用户 Cookie，开发者可以通过 [`useRuntimeContext`](/docs/guides/basic-features/data-fetch#route-loader) API 获取到请求头来实现。
+
+需要注意的是，此时获取到的是 HTML 请求的请求头，不一定适用于接口请求，因此**千万不能**透传所有请求头。并且，一些后端接口，或是通用网关，会根据请求头中的信息做校验，全量透传容易出现各种难以排查的问题，推荐**按需透传**。
+
+如果实在需要透传所有请求头，请务必过滤 `host` 字段。

package/zh/guides/advanced-features/web-server.md

@@ -1,135 +1,46 @@
 ---
-title: 扩展 Web Server
+title: 自定义 Web Server
 sidebar_position: 2
 ---
 
-有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等，这时，可以通过对 Modern.js 内置的 Web Server 进行扩展实现相应需求。
+Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
 
-## 创建定制 Web Server
+因此 Modern.js 提供了一种功能，让项目可以在给定的范围内扩展 Modern.js 内置的 Web Server，来实现相应的需求。
 
+## 创建自定义 Web Server
 
-在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「Server 自定义」功能：
-
+在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
 
 ```bash
 ? 请选择你想要的操作： 创建工程元素
-? 创建工程元素： 新建「Server 自定义」源码目录
-? 请选择运行时框架： Express/Koa/Egg/Nest
+? 创建工程元素： 新建「自定义 Web Server」源码目录
 ```
 
-目前 Modern.js 默认支持 4 种主流的 Node.js Server 框架：[Express](https://expressjs.com/)、[Koa](https://koajs.com/)、[Egg.js](https://eggjs.org/zh-cn/)、[Nest](https://nestjs.com/)，选择运行时框架时，可根据自身偏好进行选择。
-
 执行命令后，项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
 
-## 框架差异
+## 使用 API 扩展 Web Server
 
-由于不同框架 API 的差异性，自定义逻辑的写法也有所不同。假设有以下场景：当请求的 cookies 中包含 `login-token` 时，认为用户已登录，正常返回页面；否则返回 404 状态码。下面就以此场景为例，演示不同框架下如何实现定制 Web Server 逻辑。
+Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
 
-:::info 注
-目前 Modern.js 只支持前置中间件的扩展。
-:::
+### Hook
 
-### Express
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Request, Response, NextFunction } from 'express';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((request: Request, response: Response, next: NextFunction) => {
-    if (request.headers.cookies['login-token']) {
-      return next();
-    } else {
-      response.status = 401;
-      response.end();
-    }
-  });
-});
-```
+Hook 可以控制 Web Server 对请求处理的内置逻辑，非 BFF 请求会经过 Hook 的处理。
 
-### Koa
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Context, Next } from 'koa';
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx: Context, next: Next) => {
-    if (ctx.cookies['login-token']) {
-      await next();
-    } else {
-      ctx.status = 401;
-    }
-  });
-});
-```
+Hook 不可以使用运行时框架拓展。
 
-### Egg
+详细 API 可以查看 [Hook](/docs/apis/app/runtime/web-server/hook)。
 
-Egg 添加中间件的方式与 Koa 相同。
 
-```ts
-import { hook } from '@modern-js/runtime/server';
-import type { Context, Next } from 'koa';
+### Middleware
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx: Context, next: Next) => {
-    if (ctx.cookies['login-token']) {
-      await next();
-    } else {
-      ctx.status = 401;
-    }
-  });
-});
-```
+Middleware 可以为 Web Server 添加前置中间件，只有 SSR 请求会经过 Middleware 的处理。
 
-### Nest
-
-Nest 支持添加两种类型的内容：Express 的函数中间件和 Nest 中的 [Module](https:/docs.nestjs.com/modules)。
-
-Express 的函数中间件的添加与 Express 部分的示例相同，同时这里使用 Module 来为 Web Server 添加一条新的路由。
-
-```ts
-import { hook } from '@modern-js/runtime/server';
-import { Module, Injectable, Controller, Get } from '@nestjs/common';
-
-@Controller('cats')
-export class CatsController {
-  constructor(private readonly catsService: CatsService) {}
-
-  @Get()
-  getHello() {
-    return this.catsService.getHello();
-  }
-}
-
-@Injectable()
-class CatsService {
-  getHello(): string {
-    return '<div>Hello world!</div>';;
-  }
-}
-
-@Module({
-  controllers: [CatsController],
-  providers: [CatsService],
-})
-class CatsModule {}
-
-export default hook(({ addMiddleware }) => {
-  addMiddleware((request: Request, response: Response, next: NextFunction) => {
-    if (request.headers.cookies['login-token']) {
-      return next();
-    } else {
-      response.status = 401;
-      response.end();
-    }
-  });
-
-  addMiddleware(CatsModule);
-});
-```
+Middleware 可以使用运行时框架拓展。
+
+详细 API 可以查看 [Hook](/docs/apis/app/runtime/web-server/middleware)。
+
+## 完全自定义的 Web Server
 
-:::info 注
-Modern.js 中 Web Server 与应用是一体的，在开发调试、生产部署阶段都无需单独运维。
+:::note
+敬请期待
 :::

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

@@ -0,0 +1,46 @@
+---
+title: 构建能力
+sidebar_position: 2
+---
+
+**Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
+
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向现代 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+
+## 构建架构
+
+从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
+
+- 上层研发框架：Modern.js。
+- 通用构建引擎：Modern.js Builder。
+- 底层打包工具：webpack 和 rspack。
+
+<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
+
+## 构建文档
+
+由于 Modern.js Builder 是一个可独立使用的模块，我们为它提供了单独的文档，文档地址为：[modernjs.dev/builder](https://modernjs.dev/builder)。
+
+在该文档中，你可以了解到 Modern.js Builder 的详细介绍，同时也可以找到各个构建能力的完整使用指南。当你遇到构建方面的需求或问题时，建议你优先阅读 Modern.js Builder 文档来解决。
+
+## 构建配置
+
+Modern.js 的配置继承自 Modern.js Builder，因此你可以在 Modern.js 中使用 Modern.js Builder 提供的所有构建配置。
+
+以 Modern.js Builder 的 `html.title` 配置项为例，你可以直接在 `modern.config.ts` 文件中使用该配置项，它会被自动传递给 Modern.js Builder。
+
+```ts title="modern.config.js"
+export default defineConfig({
+  html: {
+    title: 'example',
+  },
+});
+```
+
+关于构建配置的详细说明，请参考 [「Modern.js Builder - Builder 配置」](https://modernjs.dev/builder/zh/guide/basic/builder-config.html)。
+
+## 构建能力
+
+Modern.js Builder 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
+
+我们推荐你阅读 [「Modern.js Builder - 功能导航」](https://modernjs.dev/builder/zh/guide/features.html) 来了解 Modern.js Builder 提供的所有构建能力。

package/zh/guides/basic-features/css/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "CSS 开发方案",
-  "position": 3
+  "position": 4
 }

package/zh/guides/basic-features/css/less-sass.md

@@ -4,20 +4,7 @@ sidebar_position: 4
 
 # Less 和 Sass
 
-[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 通过插件来提供 Less 和 Sass 编译能力的支持。
-
-## 启用 Less 或 Sass
-
-为了使用 Less 或 Sass 编译能力，我们需要先启用对应的功能。
-
-以 Less 为例，在当前项目根目录执行 new 命令, 并选择 **启用 Less 支持** 即可。
-
-```bash
-$ pnpm run new
-? 请选择你想要的操作
-? 启用可选功能 (Use arrow keys)
-❯ 启用 Less 支持
-```
+[Less](https://lesscss.org/) 和 [Sass](https://sass-lang.com/) 是常用的两种 CSS 预处理器，Modern.js 内置了 Less 和 Sass 编译能力的支持。
 
 ## 自定义配置
 

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

@@ -1,4 +1,65 @@
 ---
 title: 数据获取
-sidebar_position: 2
+sidebar_position: 3
 ---
+
+Modern.js 中提供了开箱即用的数据获取能力，开发者可以通过这些 API，在 CSR 和 SSR 环境同构的进行开发。
+
+需要注意的是，这些 API 并不帮助应用发起请求，而是帮助开发者更好的管理数据与路由的关系。
+
+## useLoader（旧版）
+
+**`useLoader`** 是 Modern.js 老版本中的 API。该 API 是一个 React Hook，专门提供给 SSR 应用使用，让开发者能同构的在组件中获取数据。
+
+:::tip
+CSR 的项目没有必要使用 `useLoader` 获取数据。
+:::
+
+以下是一个最简单的例子：
+
+```tsx
+import { useLoader } from '@modern-js/runtime';
+
+export default () => {
+  const { data } = useLoader(async () => {
+    console.log('fetch in useLoader');
+
+    // 这里没有发送真实的请求，只是返回了一个写死的数据。
+    // 真实项目中，应该返回从远端获取的数据。
+    return {
+      name: 'modern.js',
+    };
+  });
+
+  return <div>Hello, {data?.name}</div>;
+};
+```
+
+上述代码启动后，访问页面。可以看到在终端输出了日志，而在浏览器终端却没有打印日志。
+
+这是因为 Modern.js 在服务端渲染时，在会收集 `useLoader` 返回的数据，并将数据注入到响应的 HTML 中。如果 SSR 渲染成功，在 HTML 中可以看到如下代码片段：
+
+```html
+<script>
+window._SSR_DATA = {};
+</script>
+```
+
+在这全局变量中，记录了每一份数据，而在浏览器端渲染的过程中，会优先使用这份数据。如果数据不存在，则会重新执行 `useLoader` 函数。
+
+:::note
+在构建阶段，Modern.js 会自动为每个 `useLoader` 生成一个 Loader ID，并注入到 SSR 和 CSR 的 JS Bundle 中，用来关联 Loader 和数据。
+:::
+
+相比于 Next.js 中的 `getServerSideProps`，在渲染前预先获取数据。使用 `useLoader`，可以在组件中获取局部 UI 所需要的数据，而不用将数据层层传递。同样，也不会因为不同路由需要不同数据请求，而在最外层的数据获取函数中添加冗余的逻辑。当然 `useLoader` 也存在一些问题，例如服务端代码 Treeshaking 困难，服务端需要多一次预渲染等。
+
+Modern.js 在新版本中，设计了全新的 Loader 方案。新方案解决了这些问题，并能够配合**嵌套路由**，对页面性能做优化。
+
+:::note
+详细 API 可以查看 [useLoader](/docs/apis/app/runtime/core/use-loader)。
+:::
+## Route Loader
+
+:::note
+敬请期待
+:::