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

package/zh/configure/app/tools/html-plugin.md

@@ -4,7 +4,7 @@ sidebar_label: htmlPlugin
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.htmlPlugin](https://modernjs.dev/builder/zh/api/config-tools.html#tools-htmlplugin)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.htmlPlugin](https://modernjs.dev/builder/zh/api/config-tools.html#tools-htmlplugin)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/htmlPlugin.md'

package/zh/configure/app/tools/inspector.md

@@ -4,7 +4,7 @@ sidebar_label: inspector
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.inspector](https://modernjs.dev/builder/zh/api/config-tools.html#tools-inspector)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.inspector](https://modernjs.dev/builder/zh/api/config-tools.html#tools-inspector)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/inspector.md'

package/zh/configure/app/tools/less.md

@@ -4,7 +4,7 @@ sidebar_label: less
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.less](https://modernjs.dev/builder/zh/api/config-tools.html#tools-less)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.less](https://modernjs.dev/builder/zh/api/config-tools.html#tools-less)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/less.md'

package/zh/configure/app/tools/minify-css.md

@@ -4,7 +4,7 @@ sidebar_label: minifyCss
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.minifyCss](https://modernjs.dev/builder/zh/api/config-tools.html#tools-minifycss)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.minifyCss](https://modernjs.dev/builder/zh/api/config-tools.html#tools-minifycss)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/minifyCss.md'

package/zh/configure/app/tools/postcss.md

@@ -4,7 +4,7 @@ sidebar_label: postcss
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.postcss](https://modernjs.dev/builder/zh/api/config-tools.html#tools-postcss)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.postcss](https://modernjs.dev/builder/zh/api/config-tools.html#tools-postcss)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/postcss.md'

package/zh/configure/app/tools/pug.md

@@ -4,7 +4,7 @@ sidebar_label: pug
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.pug](https://modernjs.dev/builder/zh/api/config-tools.html#tools-pug)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.pug](https://modernjs.dev/builder/zh/api/config-tools.html#tools-pug)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/pug.md'

package/zh/configure/app/tools/sass.md

@@ -4,7 +4,7 @@ sidebar_label: sass
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.sass](https://modernjs.dev/builder/zh/api/config-tools.html#tools-sass)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.sass](https://modernjs.dev/builder/zh/api/config-tools.html#tools-sass)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/sass.md'

package/zh/configure/app/tools/style-loader.md

@@ -4,7 +4,7 @@ sidebar_label: styleLoader
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.styleLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styleloader)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.styleLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styleloader)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/styleLoader.md'

package/zh/configure/app/tools/styled-components.md

@@ -4,7 +4,7 @@ sidebar_label: styledComponents
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.styledComponents](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styledcomponents)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.styledComponents](https://modernjs.dev/builder/zh/api/config-tools.html#tools-styledcomponents)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/styledComponents.md'

package/zh/configure/app/tools/swc.md

@@ -0,0 +1,42 @@
+---
+title: tools.swc
+sidebar_label: swc
+---
+
+- 类型： `Object`
+- 默认值： `undefined`
+
+## 介绍
+
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且比 Babel 性能高出 10 倍不止。
+
+Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供语法降级、Polyfill 以及压缩，并且移植了一些额外常见的 Babel 插件。
+
+## 安装
+
+使用前需要安装 `@modern-js/plugin-swc` 插件，安装完成后，会自动启用 SWC 编译和压缩能力。
+
+```bash
+pnpm add @modern-js/plugin-swc -D
+```
+
+## 配置项
+
+你可以通过 `tools.swc` 配置项来设置 SWC 编译行为。
+
+```js title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  tools: {
+    swc: {
+      jsMinify: {
+        compress: {},
+        mangle: true,
+      },
+    },
+  },
+});
+```
+
+完整配置项请参考 [Modern.js Builder - SWC 插件配置](https://modernjs.dev/builder/zh/plugins/plugin-swc.html#%E9%85%8D%E7%BD%AE)。

package/zh/configure/app/tools/terser.md

@@ -4,7 +4,7 @@ sidebar_label: terser
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.terser](https://modernjs.dev/builder/zh/api/config-tools.html#tools-terser)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.terser](https://modernjs.dev/builder/zh/api/config-tools.html#tools-terser)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/terser.md'

package/zh/configure/app/tools/ts-checker.md

@@ -4,7 +4,7 @@ sidebar_label: tsChecker
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.tsChecker](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tschecker)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.tsChecker](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tschecker)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/tsChecker.md'

package/zh/configure/app/tools/ts-loader.md

@@ -4,7 +4,7 @@ sidebar_label: tsLoader
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.tsLoader](https://modernjs.dev/builder/zh/api/config-tools.html#tools-tsloader)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/tsLoader.md'

package/zh/configure/app/tools/webpack-chain.md

@@ -4,7 +4,7 @@ sidebar_label: webpackChain
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.webpackChain](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpackchain)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/webpackChain.md'

package/zh/configure/app/tools/webpack.md

@@ -4,7 +4,7 @@ sidebar_label: webpack
 ---
 
 :::info BUILDER
-该配置为 Modern.js Builder 配置，可能存在无法跳转的链接。详细信息可参考 [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
+该配置为 Modern.js Builder 配置，详细信息可参考 [tools.webpack](https://modernjs.dev/builder/zh/api/config-tools.html#tools-webpack)。
 :::
 
 import Main from '@modern-js/builder-doc/zh/config/tools/webpack.md'

package/zh/guides/advanced-features/bff/_category_.json

@@ -1,4 +1,8 @@
 {
   "label": "BFF",
-  "position": 1
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "guides/advanced-features/bff/index"
+  }
 }

package/zh/guides/advanced-features/bff/bff-proxy.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 title: 使用 BFF 代理
 ---
 
@@ -9,7 +9,7 @@ title: 使用 BFF 代理
 使用 BFF 代理需确保请求能进入 BFF handler。（例如请求路径必须包含 bff prefix）
 :::
 
-在 `modern.server-runtime.config.js` 文件中编写以下 BFF 代理配置，会将发送到 `localhost:8080/api/v1/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
+在 `modern.server-runtime.config.js` 文件中编写以下 BFF 代理配置，会将发送到 `http://localhost:8080/api/v1/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
 
 ```js title="modern.server-runtime.config.js"
 import { defineConfig } from '@modern-js/app-tools/server';
@@ -22,4 +22,6 @@ export default defineConfig({
 };
 ```
 
-具体 API 请查看 [BFF 代理](/docs/configure/app/bff/proxy)，更多 Modern.js 代理的能力可查看[调试代理](/docs/guides/basic-features/proxy)。
+:::note
+详细 API 请查看 [BFF 代理](/docs/configure/app/bff/proxy)。更多 Modern.js 代理的能力可查看[调试代理](/docs/guides/basic-features/proxy)。
+:::

package/zh/guides/advanced-features/bff/frameworks.md

@@ -1,81 +1,106 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 title: 运行时框架
 ---
 
-如前面章节所说，目前 Modern.js 的 BFF 支持 4 种主流的 Server 框架，可以根据自身偏好选择。
-
-多框架支持也是【 一体化 BFF 】中重要的一环，多数情况下，开发者直接使用钩子文件来扩展 BFF 函数，无需关心通过框架启动服务、日志输出等应用级别的问题。
+## 函数写法
 
-所有框架均支持 BFF 函数的所有能力，并且使用方式是相同的，例如：
+在函数写法下，各类运行时框架仅中间件写法存在差异，其他实现基本相同。这里以 Express 为例，介绍如何在 `api/_app.ts` 中，手写一个中间件，添加权限校验：
 
-- RESTful API
-- Schema 模式
-- Hooks(useContext)
-- 不同的数据类型
-- 动态路由
-- 一体化调用
+```ts
+import { hook } from '@modern-js/runtime/server';
+import { Request, Response, NextFunction } from 'express';
 
-Modern.js BFF 中兼容了这些框架大部分的规范，开发者可以直接使用对应 Server 框架的约定和生态。
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req: Request, res: Response, next: NextFunction) => {
+    if (req.url !== '/api/login') {
+      const sid = req?.cookies?.sid;
+      if (!sid) {
+        res.status(400);
+        res.json({ code: -1, message: 'need login' });
+      } else {
+        next();
+      }
+    } else {
+      next();
+    }
+  });
+});
+```
 
-每一种框架都提供了两类扩展写法 BFF 函数的方式，分别是【 函数写法 】和【 框架写法 】。
+然后添加一个普通的 BFF 函数 `/api/hello.ts`：
 
-## 函数写法
+```ts
+export default async () => {
+  return 'Hello Modern.js';
+};
+```
 
-在上一章节中，简单的演示了 Express 扩展 BFF 函数的示例。
+最后在前端 `src/App.tsx` 添加接口的访问代码，直接使用一体化的方式调用：
 
-函数写法就是通过添加钩子文件 `_app.ts` 的方式，编写中间件逻辑来扩展 BFF 函数。
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
 
-### [Express](https://expressjs.com/)
+export default () => {
+  const [text, setText] = useState('');
 
-Express 的函数写法，可以通过在 `_app.[tj]s` 下添加 `express` 的中间件：
+  useEffect(() => {
+    async function fetchMyApi() {
+      const { message } = await hello();
+      setText(message);
+    }
 
-```ts
-import { hook } from "@modern-js/runtime/server";
+    fetchMyApi();
+  }, []);
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (req, res, next) => {
-    req.query.id = "express";
-    await next();
-  });
-});
+  return <p>{text}</p>;
+};
 ```
 
-### [Koa](https://koajs.com/)
+然后 `pnpm run dev` 启动项目，访问 `http://localhost:8080/` 会发现 `/api/hello` 的请求被拦截了：
 
-Koa 函数写法下，可以通过在 `_app.[tj]s` 下添加 koa 的中间件：
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network2.png)
 
-```ts
-import { hook } from "@modern-js/runtime/server";
+最后再修改前端代码 `src/App.tsx`，在访问 `/api/hello` 前先调用登录接口：
 
-export default hook(({ addMiddleware }) => {
-  addMiddleware(async (ctx, next) => {
-    console.info(`access url: ${ctx.url}`);
-    next();
-  });
-});
+```ts
+import { useState, useEffect } from 'react';
+import { get as hello } from '@api/hello';
+import { post as login } from '@api/login';
+
+export default () => {
+  const [text, setText] = useState('');
+
+  useEffect(() => {
+    async function fetchAfterLogin() {
+      const { code } = await login();
+      if (code === 0) {
+        const { message } = await hello();
+        setText(message);
+      }
+    }
+    fetchAfterLogin();
+  }, []);
+
+  return <p>{text}</p>;
+};
 ```
 
-## 框架写法
+刷新页面，可以看到 `/api/hello` 访问成功：
 
-框架写法是一种使用框架分层结构来扩展 BFF 函数的方式。
+![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/network3.png)
 
-和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
+以上代码模拟了在 `/api/_app.ts` 中添加中间件的方式，实现了简易的登录功能。同样，可以在这个钩子文件中实现其他功能来扩展 BFF Server。
 
-:::info 注
-多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时（如 egg 插件），才需要使用框架写法。
-:::
+## 框架写法
 
-框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
+框架写法下，Modern.js 不会收集 `api/_app.ts` 中的中间件，运行流程由插件自行控制。
 
 ### Express
 
 Express 的框架写法支持可在 `api/app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，甚至扩展原有框架等。
 
-:::info 注
-注意这里是 `app.[tj]s`，而不是函数写法中的钩子文件 `_app.[tj]s`。
-:::
-
 BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
 
 ```ts title="api/app.ts"
@@ -99,10 +124,6 @@ export default app;
 
 Koa 框架写法与 Express 类似，支持在 `app.[tj]s` 定义 API Server 的启动逻辑，执行应用的初始化工作，添加全局中间件，声明路由，扩展原有框架等。
 
-:::info 注
-注意这里是 `app.[tj]s`，而不是函数写法中的钩子文件 `_app.[tj]s`。
-:::
-
 BFF 函数定义的路由会在 `app.ts` 文件定义的路由之后注册，所以在这里你也可以拦截 BFF 函数定义的路由，进行预处理或是提前响应。
 
 :::caution 注意

package/zh/guides/advanced-features/bff/function.md

@@ -1,41 +1,23 @@
 ---
 sidebar_position: 1
-title: BFF 函数
+title: 一体化调用
 ---
 
-在[一体化 Web 专题](/docs/guides/basic-features/routes)中，介绍过 Modern.js 的 Serverless Web Development 开发方式，包括自动化路由、内置 Web Server、一体化 SSG/SSR/SPR 等。其中的 SSR 技术，可以称作 Serverless SSR，实现了 SSR 在开发、运行、部署全流程中的 Serverless。
+Modern.js 允许在 React 组件中直接调用 `api/` 目录下满足一定条件的函数，称为**一体化调用**。
 
-这一专题中会详细介绍另一部分：Serverless BFF。跟 SSR 一样，能实现 BFF（Backends for Frontends）在开发、运行、部署全流程中的 Serverless。
-
-在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF 这一概念。
-
-它主要为了解决的问题包括：
-
-* 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
-* 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
-* 根据已有接口快速开发新产品。
-* 与第三方系统对接，例如登陆鉴权。
-
-Modern.js 提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
-
-* 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
-* 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
-* 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
-* 完善的 TypeScript 支持。
-* 满足用户使用偏好，支持多框架扩展写法。
-* 接口调用安全，提供 schema 的接口定义方式。
-
-## 一体化调用
+:::note
+使用一体化调用需要先开启 BFF 功能。
+:::
 
-Modern.js 允许可以在 `src` 目录下的 React 组件中直接引入并调用在 `api` 目录下定义好函数。
+## BFF 函数
 
-[开启 BFF 功能](/docs/tutorials/first-app/c09-bff/9.2-enable-bff)之后，创建 `api/hello.ts` 文件，这里定义一个最简单的 BFF 函数：
+允许通过一体化调用的函数，称为 **BFF 函数**。这里写一个最简单的 BFF 函数，创建 `api/hello.ts` 文件：
 
 ```ts title="api/hello.ts"
 export const get = async () => 'Hello Modern.js';
 ```
 
-接着在 `src` 下的 `App.tsx` 中直接 import 函数调用：
+接着在 `src/App.tsx` 中直接引入函数并调用：
 
 ```tsx title=src/App.tsx
 import { useState, useEffect } from 'react';
@@ -57,7 +39,7 @@ Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可
 
 在 `src/App.tsx` 中引入的函数，会自动转换成接口调用，不需要再去通过 fetch 去调用接口。
 
-执行 `pnpm run dev` 打开 <http://localhost:8080/> 可以看到页面已经展示了 BFF 函数返回的内容，在Network，可以看到页面向 <http://localhost:8080/api/hello> 发送了请求：
+执行 `pnpm run dev` 打开 `http://localhost:8080/` 可以看到页面已经展示了 BFF 函数返回的内容，在 Network 中可以看到页面向 `http://localhost:8080/api/hello` 发送了请求：
 
 ![Network](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/hello-modern.png)
 
@@ -65,12 +47,16 @@ Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可
 
 Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，也是一种**约定式路由**。
 
-函数模式下 `api` 下的所有文件中的每个 BFF 函数都会映射为一个接口，框架模式下 `api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口。
+函数写法下 `api/` 下的所有文件中的每个 BFF 函数都会映射为一个接口。框架写法下 `api/lambda` 下的所有文件中的每个 BFF 函数都会映射为一个接口。
+
+:::note
+函数写法和框架写法会在下一节详细介绍。
+:::
 
 以下的 `$BASENAME` 指的是 BFF 函数的[路由前缀](/docs/configure/app/bff/prefix)，可以在 `modern.config.js` 中进行配置，默认值为 `/api`。
 
 :::info 注
-你可以通过 [prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
+可以通过 [bff.prefix](/docs/configure/app/bff/prefix) 设置公共路由的前缀。
 :::
 
 ### 默认路由
@@ -89,7 +75,7 @@ Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，
 
 ### 动态路由
 
-同样的，你可以通过创建命名带有 `[xxx]` 的文件夹或者文件来支持动态的命名路由参数。
+同样的，创建命名带有 `[xxx]` 的文件夹或者文件，支持动态的命名路由参数。
 
 * `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
 * `api/user/username/[action].ts` -> `$BASENAME/user/username/:action`

package/zh/guides/advanced-features/bff/index.md

@@ -0,0 +1,20 @@
+---
+title: BFF
+---
+
+在**前后端分离**概念出现后一段时间发展中，前端部分能够做的事越来越多，前端需要一些面向 UI 的数据接口，因此业界引入了 BFF（Backends for Frontends）这一概念。
+
+它主要为了解决的问题包括：
+
+* 根据自身业务需求，对更底层 API 的聚合、映射、裁剪、代理。
+* 对一些特定场景的数据进行缓存，提高性能，进而提升用户体验。
+* 根据已有接口快速开发新产品。
+* 与第三方系统对接，例如登陆鉴权。
+
+Modern.js 官方支持了 BFF，并提供了**一体化 BFF 方案**来进一步强化 BFF 能力，主要包括以下能力：
+
+* 快速开发调试上线，在同一项目中运行、构建、部署 BFF 代码。
+* 极简的纯函数调用，在前端直接 import BFF 函数，调用时能自动转换成 HTTP 请求。
+* 无私有协议，遵循 RESTful API 规范，所有 BFF 接口都是标准化的。
+* 完善的 TypeScript 支持。
+* 满足用户使用偏好，支持多框架扩展写法。

package/zh/guides/advanced-features/bff/type.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 2
+title: 函数写法 & 框架写法
+---
+
+运行时框架支持也是 **BFF** 中重要的一环。Modern.js 支持通过插件扩展 BFF 的运行时框架，并提供了一系列内置插件，开发者可以直接使用对应框架的约定和生态。
+
+插件中兼容了这些框架大部分的规范，每一种框架都需要提供两类扩展写法 BFF 函数的方式，分别是**函数写法**和**框架写法**。
+
+:::note
+当前 `api/` 目录结构是否为框架写法由对应的插件决定，Modern.js 并不关心。
+:::
+
+## 函数写法
+
+当插件认为当前为函数写法时，必须支持在 `api/_app.ts` 中编写中间件，用来扩展 BFF 函数。
+
+Modern.js 会收集 `api/_app.ts` 中的中间件，并传递给插件，由插件将中间件注入运行时，例如：
+
+```ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(myMiddleware);
+});
+```
+
+:::note
+不同插件的中间件的写法不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
+:::
+
+## 框架写法
+
+框架写法是一种使用框架结构来扩展 BFF 函数的方式。和函数写法相比，框架写法虽然能够利用更多框架的结构，在复杂场景下让整个 BFF Server 更加清晰，但也相的更加复杂，需要关心更多框架层面的内容。
+
+框架写法中，所有的 BFF 函数都需要写在 `api/lambda/` 目录下，并且无法使用钩子文件 `_app.[tj]s`。
+
+多数情况下，函数写法就能覆盖大多数 BFF 函数的定制需求。只有当你的项目服务端逻辑比较复杂，代码需要分层，或者需要使用更多框架的元素时，才需要使用框架写法。
+
+:::note
+不同插件框架写法的目录结构不一定相同，详情可见[运行时框架](/docs/guides/advanced-features/bff/frameworks)。
+:::
+

package/zh/guides/advanced-features/custom-app.md

@@ -1,4 +1,72 @@
 ---
-title: 自定义入口
+title: 自定义 App
 sidebar_position: 7
 ---
+
+在[入口](/docs/guides/concept/entries)概念中提到， Modern.js 提供了三种文件约定来标记入口。
+
+通常情况下，`routes/` 与 `App.[jt]sx` 两种模式已经能够满足需求。当开发者需要在根组件挂载前做些操作，或者完全接管 Webpack 入口时，可以在入口目录下放置 `index.[jt]sx` 文件，我们称为**自定义 App**。
+
+## 添加自定义行为
+
+当 `index` 文件默认导出**函数**是，Modern.js 还是会根据 `runtime` 的设置情况生成 `createApp` 包裹后的代码。在渲染过程中，将 `createApp` 包裹后的组件作为参数传递给 `index` 文件导出的函数，这样开发者可以自定义将组件挂载到 DOM 节点上，或在挂载前添加自定义行为。例如：
+
+```js title=src/index.jsx
+import ReactDOM from 'react-dom/client'
+import { bootstrap } from '@modern-js/runtime';
+
+
+export default App => {
+  // do something before bootstrap...
+  bootstrap(App, 'root', undefined, ReactDOM);
+};
+```
+
+:::warning
+由于 bootstrap 函数需要兼容 React17 和 React18 的用法，调用 bootstrap 函数时需要手动传入 ReactDOM 参数。
+:::
+
+Modern.js 生成的文件内容如下：
+
+```js
+import customRender from '@/src/index.js';
+import { createApp, bootstrap } from '@modern-js/runtime';
+import React from 'react';
+import App from '@/src/App';
+
+const IS_BROWSER = typeof window !== 'undefined';
+const MOUNT_ID = 'root';
+
+let AppWrapper = null;
+
+const renderApp = () => {
+  AppWrapper = createApp({
+    // runtime 的插件参数...
+  })(App);
+  customRender(AppWrapper);
+};
+
+renderApp();
+
+export default AppWrapper;
+
+if (IS_BROWSER && module.hot) {
+  module.hot.accept('<path>/src/App', () => {
+    renderApp();
+  });
+}
+```
+
+## 完全接管 Webpack 入口
+
+当 `index.[jt]sx` 文件没有导出函数时，这时候该文件就是真正的 Webpack 入口文件。这里和 [Create React App](https://github.com/facebook/create-react-app) 类似，需要自己将组件挂载到 DOM 节点、添加热更新代码等。例如:
+
+```js title=src/index.jsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+```
+
+Modern.js **不推荐**使用这种方式，这种方式丧失了框架的一些能力，如 **`modern.config.js` 文件中的 `runtime` 配置将不会再生效**。