@modern-js/main-doc 0.0.0-next-20230302055919 → 0.0.0-next-20230302092418

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @modern-js/main-doc@2.6.0 build /tmp/repo/modern.js/packages/toolkit/main-doc
+> @modern-js/main-doc@2.7.0 build /github/workspace/packages/toolkit/main-doc
 > npx ts-node ./scripts/sync.ts
 

package/CHANGELOG.md

@@ -1,8 +1,9 @@
 # @modern-js/main-doc
 
-## 0.0.0-next-20230302055919
+## 0.0.0-next-20230302092418
 
 ### Patch Changes
 
-- Updated dependencies [54caf4334]
-  - @modern-js/builder-doc@0.0.0-next-20230302055919
+- ea7bb41e30: feat: add custom web server docs
+  feat: 添加自定义 Web Server 文档
+  - @modern-js/builder-doc@0.0.0-next-20230302092418

package/en/apis/app/runtime/web-server/hook.mdx

@@ -3,7 +3,7 @@ title: Hook
 ---
 # Hook
 
-Used to extend Modern.js built-in Web Server, requests except BFF are handled by these hooks.
+Used to extend Modern.js built-in Web Server, all page requests are handled by these hooks.
 
 :::note
 For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
@@ -63,7 +63,7 @@ type HookContext = {
 function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
 ```
 
-different Hooks additionally provide different contexts. Currently Modern.js support `AtferMatch` and `AfterRender`.
+different Hooks additionally provide different contexts. Currently Modern.js support `AfterMatch` and `AfterRender`.
 
 ```ts
 type AfterMatchContext = HookContext & {

package/en/apis/app/runtime/web-server/middleware.mdx

@@ -3,9 +3,7 @@ title: Middleware
 ---
 # Middleware
 
-Used to extend Modern.js built-in Web Server, only SSR requests are handled by these middleware.
-
-Unlike [Hook](/apis/app/runtime/web-server/hook), middleware can be extended using the framework plugin.
+Used to extend the built-in Web Server of Modern.js, unlike [Hook](/apis/app/runtime/web-server/hook), Middleware can directly operate Node's origin request and response, and can be extended using the framework plugin.
 
 :::note
 For more detail, see [Extend Web Server](/guides/advanced-features/web-server).
@@ -38,6 +36,11 @@ pnpm run new
 ## Function Signature
 
 ```ts
+type Middleware = (
+  context: MiddlewareContext,
+  next: NextFunction,
+) => Promise<void> | void;
+
 type MiddlewareContext = {
   response: {
     set: (key: string, value: string) => void;
@@ -70,11 +73,6 @@ type MiddlewareContext = {
     res: ServerResponse;
   };
 };
-
-type RequestHandler = (
-  context: Context,
-  next: NextFunction,
-) => Promise<void> | void;
 ```
 
 ### Input
@@ -85,6 +83,10 @@ type RequestHandler = (
   - `source`: provides Node.js native `req` and `res` object.
 - `next`: call next listener（not affect the server process, only current hook）.
 
+:::warning
+The execution of the `next` function does not affect built-in processes, only controls whether the next middleware executes. Rendering processes are interrupted only when the response is written.
+:::
+
 ## Example
 
 ### Tracking
@@ -106,5 +108,27 @@ Modern.js provides `res.locals` to store local variables for the current request
 export const Middleware = () => async (ctx, next) => {
   ctx.res.locals.id = 'Modern.js';
   ctx.res.locals.rpc = createRpcInstance();
-});
+};
 ```
+
+### Framework Extension
+
+Middleware can also use runtime framework extensions like BFF.
+
+When using framework runtime extensions, type information is exported from `@modern-js/runtime/{namespace}`. Middleware can use framework syntax, such as framework middleware writing, the following is pseudo-code:
+
+```ts
+import { SomeType } from '@modern-js/runtime/{namespace}';
+
+export const middleware: SomeType = (ctx, next) => {
+  console.log(ctx.url);
+  next();
+};
+```
+
+By default, the framework extension capability of Web Server is turned off after installing the framework extension plug-in. If you want to use the framework extension, you can turn it on through ['server.enableFrameworkExt'](/configure/app/server/enable-framework-ext.html).
+
+
+:::info
+The type name exported by the framework extension may not 'Middleware', but is named by the framework extension plugin.
+:::

package/en/configure/app/bff/enable-handle-web.mdx

@@ -0,0 +1,24 @@
+---
+title: enableHandleWeb
+---
+
+# bff.enableHandleWeb
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+:::caution
+First you need to enable the "BFF" function using [new](/apis/app/commands#modern-new) command.
+:::
+
+By default, the BFF service can only handle requests from the BFF API.
+
+When this value is set to `true`, page request traffic also goes through the BFF, and the logic built into Modern.js for page rendering defaults to running as the last middleware for the BFF service.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```

package/en/configure/app/server/enable-framework-ext.mdx

@@ -35,7 +35,7 @@ export const middleware: Middleware = (ctx, next) => {
 When enabled, Middleware types will be exported from other namespaces and can the syntax of framework extensions:
 
 ```ts title="server/index.ts"
-import { SomeType } from '@modern-js/runtime/{frameworknName}';
+import { SomeType } from '@modern-js/runtime/{namespace}';
 
 export const middleware: SomeType = (...args) => {
   console.log(args[0].url);

package/en/guides/advanced-features/rspack-start.mdx

@@ -5,7 +5,7 @@ sidebar_position: 12
 
 # Rspack Start
 
-[Rspack](https://www.rspack.org/) is a Rust-based web bundler developed by the ByteDance Web Infra team. The core architecture of Rspack is aligned with the implementation of webpack, and provides out-of-the-box support for commonly used build features.
+[Rspack](https://www.rspack.dev/) is a Rust-based web bundler developed by the ByteDance Web Infra team. The core architecture of Rspack is aligned with the implementation of webpack, and provides out-of-the-box support for commonly used build features.
 
 Rspack optimizes compilation performance by:
 
@@ -13,9 +13,9 @@ Rspack optimizes compilation performance by:
 - Take full advantage of multi-core, and the entire compilation process is fully optimized for multi-threading.
 - On-demand compilation based on request (Lazy Compilation), reducing the number of modules per compilation to improve the speed of cold start.
 
-## Initializing an rspack project
+## Initializing an Rspack project
 
-The Modern.js generator provides an interactive question-and-answer interface to initialize a project. To create an rspack project, simply select the **rspack** build tool by running:
+The Modern.js generator provides an interactive question-and-answer interface to initialize a project. To create an Rspack project, simply select the **rspack** build tool by running:
 
 ```bash
 $ npx @modern-js/create myapp
@@ -28,7 +28,7 @@ $ npx @modern-js/create myapp
 After the project is created, you can experience the project by running `pnpm run dev`. For more project information, please refer to [Quick Start](/guides/get-started/quick-start.html).
 
 :::tip
-When using rspack as the bundler, the following features are currently not supported:
+When using Rspack as the bundler, the following features are currently not supported:
 
 - Server-side rendering (SSR)
 - Static Site Generation (SSG)
@@ -37,17 +37,17 @@ When using rspack as the bundler, the following features are currently not suppo
 
 :::
 
-## Migrating from webpack to rspack
+## Migrating from webpack to Rspack
 
-You can enable rspack build by running `pnpm run new`:
+You can enable Rspack build by running `pnpm run new`:
 
 ```bash
 $ pnpm run new
 ? Action： Enable features
-? Enable features： Enable rspack Build
+? Enable features： Enable Rspack Build
 ```
 
-After executing the command, enable the rspack build in `modern.config.ts`:
+After executing the command, enable the Rspack build in `modern.config.ts`:
 
 ```ts title=modern.config.ts
 import appTools, { defineConfig } from '@modern-js/app-tools';
@@ -65,5 +65,5 @@ export default defineConfig<'rspack'>({
 ```
 
 :::tip
-Migrating from webpack to rspack may have some differences in build and configuration capabilities. For more details, please refer to [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack)
+Migrating from webpack to Rspack may have some differences in build and configuration capabilities. For more details, please refer to [Configuration Differences](https://modernjs.dev/builder/en/guide/advanced/rspack-start.html#migrating-from-webpack-to-rspack)
 :::

package/en/guides/advanced-features/web-server.mdx

@@ -4,20 +4,34 @@ sidebar_position: 2
 ---
 # Custom Web Server
 
-Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
+As a client side-centric development framework, Modern.js has weak customization capabilities on the server side. In some development scenarios, special server level logic needs to be customized, such as user authentication, request preprocessing, and adding page rendering skeletons.
 
-因此 Modern.js 提供了一种功能，让项目可以在给定的范围内扩展 Modern.js 内置的 Web Server，来实现相应的需求。
+Some developers may be wondering, Modern.js already provides [BFF](/guides/advanced-features/bff/function.html), why do you need **Custom Web Server**.
 
-## 创建自定义 Web Server
+Because by default, page routing does not go through BFF, it has no way to provide server-side custom logic for page access. The reason for this design is that we do not want the service that controls the page to be bound to the BFF service, so as to avoid the BFF framework restricting how the page is deployed.
 
-在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
+For example, hosting pages separately from BFF, deploying page services to non-Node environments, or customizing for deployment platforms, etc.
+
+For the above reasons, Modern.js provides three ways that projects can customize server level capabilities progressively according to their needs.
+
+:::warning
+The three extension methods cannot work at the same time, and developers need to choose the appropriate method according to the scenario.
+:::
+
+## Extending Web Server with API
+
+The first way is to customize the server level at a specific life cycle through the server level runtime API provided by Modern.js. The purpose of providing this way is that in some cases, developers do not need to control the full Web Server, but only need to add server level logic.
+
+Because the full web server cannot be controlled this way, and the extension logic **only takes effect when the page is requested**. Therefore, it is relatively simple to apply to server level logic, and you do not want to create additional BFFs or BFFs and pages without common server level logic scenarios.
+
+You can execute the'pnpm run new 'command in the project root directory to enable the "Custom Web Serve" function:
 
 ```bash
-? 请选择你想要的操作 创建工程元素
-? 创建工程元素 新建「自定义 Web Server」源码目录
+? Action Create project element
+? New "Custom Web Server" source code directory
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 Server 插件:
+After executing the command, register the `@modern-js/plugin-server` plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import serverPlugin from '@modern-js/plugin-server';
@@ -27,31 +41,84 @@ export default defineConfig({
 });
 ```
 
-项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
+After the function is turned on, the `server/index.ts` file will be automatically created in the project directory, and custom logic can be written in this file. Modern.js provides two types of APIs, **Hook** and **Middleware**, to extend Web Server.
+
+### Hook
 
-## 使用 API 扩展 Web Server
+The Hook provided by Modern.js is used to control the built-in logic in the Web Server, and all page requests go through the Hook.
 
-Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
+There are currently two Hooks provided, namely `AfterMatch` and `AfterRender`, which can be used to modify the rendering results. It can be written in `server/index.ts` like this:
 
-### Hook
+```ts
+import type { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (ctx, next) => {
+  next();
+}
+
+export const afterRender: AfterRenderHook = (ctx, next) => {
+  next();
+}
+```
 
-Hook 可以控制 Web Server 对请求处理的内置逻辑，非 BFF 请求会经过 Hook 的处理。
+Projects should have the following best practices when using Hook:
 
-Hook 不可以使用运行时框架拓展。
+1. Permission verification in afterMatch.
+2. Do Rewrite and Redirect in afterMatch.
+3. Do HTML content injection in afterRender.
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/hook)。
+:::note
+For more detail, see [Hook](/apis/app/runtime/web-server/hook)。
+:::
 
 ### Middleware
 
-Middleware 可以为 Web Server 添加前置中间件，只有 SSR 请求会经过 Middleware 的处理。
+For some projects, there may be more requirements at the server level, Modern.js provides Middleware to add pre-middleware for Web Server. It can only run in a Node environment, so if the project is deployed to another environment, such as a Worker environment, Middleware cannot be used.
 
-Middleware 可以使用运行时框架拓展。
+Modern.js provides a set of APIs by default for projects to use:
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/middleware)。
+```ts
+import { Middlewre } from '@modern-js/runtime/server';
 
-## 完全自定义的 Web Server
+export const middleware = (context, next) => {
+  const { source: { req, res } } = context;
+  console.log(req.url);
+  next();
+};
+```
 
 :::note
-敬请期待
+For more detail, see [Middleware] (/apis/app/runtime/web-server/middleware).
+:::
+
+Projects should have the following best practices when using Middleware:
+
+1. In Middleware, you can directly operate origin request and response objects, do event tracking, and inject Node services (databases, Redis, etc.) that may be used for SSR rendering.
+2. Marking and crawler optimization can be done in Middleware.
+3. In Middleware, you can ignore the default rendering and customize the rendering process.
+
+**In general, in CSR projects, using Hook can basically meet all the needs of simple scenarios. In SSR projects, Middleware can be used for more complex Node extensions.**
+
+## Managed Page Requests with BFF
+
+The second way is to use BFF to Managed page rendering. In this way, all requests will first hit the BFF service.
+
+This method can uniformly control the server level logic of all requests through BFF. Therefore, it is suitable for scenarios where the server level logic is complex, and BFF and pages need common server level logic. But it still relies on the Web Server of Modern.js as a whole, and cannot run the logic on existing services.
+
+To use this method, we need to first enable the "BFF" function through `pnpm new`. Then add [`bff.enableHandleWeb`](/configure/app/bff/enable-handle-web.html) configuration in the configuration file:
 
+```ts
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```
+
+When this value is set to `true`, page request traffic also goes through the BFF, and the logic built into Modern.js for page rendering defaults to running as the last middleware for the BFF service.
+
+## Fully Customized Web Server
+
+:::note
+Comming soon..
 :::

package/package.json

@@ -11,13 +11,13 @@
     "modern",
     "modern.js"
   ],
-  "version": "0.0.0-next-20230302055919",
+  "version": "0.0.0-next-20230302092418",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "0.0.0-next-20230302055919"
+    "@modern-js/builder-doc": "^0.0.0-next-20230302092418"
   },
   "devDependencies": {
     "ts-node": "^10",
@@ -25,7 +25,7 @@
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "0.0.0-next-20230302055919"
+    "@modern-js/builder-doc": "0.0.0-next-20230302092418"
   },
   "scripts": {
     "build": "npx ts-node ./scripts/sync.ts"

package/zh/apis/app/runtime/web-server/hook.mdx

@@ -3,11 +3,10 @@ title: Hook
 ---
 # Hook
 
-用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
+用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
 
 :::note
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
-
 :::
 
 ## 使用姿势
@@ -27,7 +26,6 @@ pnpm run new
 ? 请选择你想要的操作 创建工程元素
 ? 新建「自定义 Web Server」源码目录
 ```
-
 :::
 
 ## 函数签名
@@ -64,7 +62,7 @@ type HookContext = {
 function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
 ```
 
-另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AtferMatch` 和 `AfterRender` 两个 Hook。
+另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AfterMatch` 和 `AfterRender` 两个 Hook。
 
 ```ts
 type AfterMatchContext = HookContext & {

package/zh/apis/app/runtime/web-server/middleware.mdx

@@ -3,13 +3,10 @@ title: Middleware
 ---
 # Middleware
 
-用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
-
-与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
+用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
 
 :::note
 更多内容可以查看[自定义 Web Server](/guides/advanced-features/web-server)。
-
 :::
 
 ## 使用姿势
@@ -38,6 +35,11 @@ pnpm run new
 ## 函数签名
 
 ```ts
+type Middleware = (
+  context: MiddlewareContext,
+  next: NextFunction,
+) => Promise<void> | void;
+
 type MiddlewareContext = {
   response: {
     set: (key: string, value: string) => void;
@@ -71,11 +73,6 @@ type MiddlewareContext = {
     res: ServerResponse;
   };
 };
-
-type RequestHandler = (
-  context: Context,
-  next: NextFunction,
-) => Promise<void> | void;
 ```
 
 ### 参数
@@ -86,6 +83,10 @@ type RequestHandler = (
   - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
 - `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
 
+:::warning
+`next` 函数的执行不影响后续内置流程，只控制下一个中间件是否执行。只有当响应被写入时，后续渲染流程才会中断。
+:::
+
 ## 示例
 
 ### 服务端耗时打点
@@ -107,5 +108,24 @@ Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量
 export const Middleware = () => async (ctx, next) => {
   ctx.res.locals.id = 'Modern.js';
   ctx.res.locals.rpc = createRpcInstance();
-});
+};
 ```
+
+### 框架拓展
+
+Middleware 还可以和 BFF 一样，使用运行时框架拓展。Modern.js 约定，当使用框架运行时拓展时，类型信息从 `@modern-js/runtime/{namespace}` 下导出，Middleware 可以使用框架语法，例如框架中间件写法，以下是伪代码：
+
+```ts
+import { SomeType } from '@modern-js/runtime/{namespace}';
+
+export const middleware: SomeType = (ctx, next) => {
+  console.log(ctx.url);
+  next();
+};
+```
+
+默认情况下，在安装框架拓展插件后，Web Server 的框架拓展能力是关闭的。如果希望使用框架拓展，可以通过 [`server.enableFrameworkExt`](/configure/app/server/enable-framework-ext.html) 开启。
+
+:::info
+框架拓展导出的类型名不一定为 Middleware，命名由框架拓展插件。
+:::

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

@@ -0,0 +1,24 @@
+---
+title: enableHandleWeb
+---
+
+# bff.enableHandleWeb
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+:::caution 注意
+请先在当前应用项目根目录使用【[new](/apis/app/commands#modern-new)】 启用 BFF 功能。
+:::
+
+默认情况下，BFF 服务只能处理 BFF API 的请求。
+
+当该值设置为 `true` 时，页面请求流量也会经过 BFF，并且 Modern.js 内置的页面渲染的逻辑默认会作为 BFF 服务的最后一个中间件运行。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```

package/zh/configure/app/server/enable-framework-ext.mdx

@@ -35,7 +35,7 @@ export const middleware: Middleware = (ctx, next) => {
 开启后，Middleware 类型将从其他命名空间下导出，并且可以使用框架拓展的语法：
 
 ```ts title="server/index.ts"
-import { SomeType } from '@modern-js/runtime/{frameworknName}';
+import { SomeType } from '@modern-js/runtime/{namespace}';
 
 export const middleware: SomeType = (...args) => {
   console.log(args[0].url);

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

@@ -5,7 +5,7 @@ sidebar_position: 12
 
 # 使用 Rspack
 
-[Rspack](https://www.rspack.org/) 是字节跳动 Web Infra 团队自研的 Rust Bundler，核心架构对齐 webpack 实现，并对社区常用的构建能力做了开箱即用的支持。
+[Rspack](https://www.rspack.dev/) 是字节跳动 Web Infra 团队自研的 Rust Bundler，核心架构对齐 webpack 实现，并对社区常用的构建能力做了开箱即用的支持。
 
 Rspack 通过以下方式来提升编译性能：
 
@@ -13,9 +13,9 @@ Rspack 通过以下方式来提升编译性能：
 - 充分利用多核优势，整个编译过程充分进行多线程优化。
 - 基于请求的按需编译（Lazy Compilation），减小每次编译的模块数目，以提升冷启动的速度。
 
-## 初始化 rspack 项目
+## 初始化 Rspack 项目
 
-Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为**rspack**，即可创建一个 rspack 项目:
+Modern.js 生成器会提供一个可交互的问答界面，只需将构建工具选择为**rspack**，即可创建一个 Rspack 项目:
 
 ```bash
 $ npx @modern-js/create myapp
@@ -28,7 +28,7 @@ $ npx @modern-js/create myapp
 项目创建完成后，在项目中执行 `pnpm run dev` 即可体验项目。更多项目信息可参考[快速上手](/guides/get-started/quick-start.html)。
 
 :::tip
-使用 rspack 作为打包工具时，以下功能暂不支持使用:
+使用 Rspack 作为打包工具时，以下功能暂不支持使用:
 
 - 服务端渲染（SSR）
 - 静态站点生成（SSG）
@@ -37,17 +37,17 @@ $ npx @modern-js/create myapp
 
 :::
 
-## 从 webpack 迁移至 rspack
+## 从 webpack 迁移至 Rspack
 
-通过执行 `pnpm run new` 可启用 rspack 构建：
+通过执行 `pnpm run new` 可启用 Rspack 构建：
 
 ```bash
 $ pnpm run new
 ? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「rspack 构建」
+? 启用可选功能 启用「Rspack 构建」
 ```
 
-执行命令后，在 modern.config.ts 中开启 rspack 构建：
+执行命令后，在 modern.config.ts 中开启 Rspack 构建：
 
 ```ts title=modern.config.ts
 import appTools, { defineConfig } from '@modern-js/app-tools';
@@ -65,5 +65,5 @@ export default defineConfig<'rspack'>({
 ```
 
 :::tip
-从 webpack 迁移至 rspack，会有一些构建和配置能力上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
+从 webpack 迁移至 Rspack，会有一些构建和配置能力上的差异，详情可参考：[配置差异](https://modernjs.dev/builder/guide/advanced/rspack-start.html#从-webpack-迁移到-rspack)
 :::

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

@@ -6,18 +6,30 @@ sidebar_position: 2
 
 Modern.js 作为以客户端为中心的开发框架，对服务端的定制能力较弱。而在有些开发场景下，需要定制特殊的服务端逻辑，例如用户鉴权、请求预处理、添加页面渲染骨架等。
 
-因此 Modern.js 提供了一种功能，让项目可以在给定的范围内扩展 Modern.js 内置的 Web Server，来实现相应的需求。
+一些开发者可能会有疑惑，Modern.js 已经提供了 [BFF 能力](/guides/advanced-features/bff/function.html)，为什么还需要**自定义 Web Server**。
 
-## 创建自定义 Web Server
+因为在默认情况下，页面路由并不会经过 BFF，它没有办法为页面访问提供服务端的定制逻辑。之所以这样设计，是因为我们不希望控制页面的服务与 BFF 服务绑定在一起，避免 BFF 的框架限制页面的部署方式。例如将页面与 BFF 分开托管、将页面服务部署到非 Node 的环境上，或是针对部署平台做定制等。
 
-在项目根目录执行 `pnpm run new` 命令，按照如下选择，开启「自定义 Web Serve」功能：
+出于上述原因，Modern.js 提供了三种方式，让项目可以在根据需求，渐进式的定制服务端能力。
+
+:::warning
+三种扩展方式无法同时工作，开发者需要根据场景选择合适的方式。
+:::
+
+## 使用 API 扩展 Web Server
+
+第一种方式是通过 Modern.js 提供的服务端运行时 API，在特定的生命周期对服务端进行定制。提供这种方式的目的是在部分情况下，开发者并不需要控制完整的 Web Server，只需要添加服务端逻辑即可。
+
+这种方式无法控制完整的 Web Server，并且扩展逻辑**只在请求页面时生效**。因此，它适用于服务端逻辑相对简单，不希望额外创建 BFF 或者 BFF 和页面无需公用服务端逻辑场景。
+
+可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Serve」功能：
 
 ```bash
 ? 请选择你想要的操作 创建工程元素
 ? 创建工程元素 新建「自定义 Web Server」源码目录
 ```
 
-执行命令后，在 `modern.config.ts` 中注册 Server 插件:
+执行命令后，在 `modern.config.ts` 中注册 `@modern-js/plugin-server` 插件:
 
 ```ts title="modern.config.ts"
 import serverPlugin from '@modern-js/plugin-server';
@@ -27,31 +39,84 @@ export default defineConfig({
 });
 ```
 
-项目目录下会新建 `server/index.ts` 文件，自定义逻辑在这个文件中编写。
+开启功能后，项目目录下会自动创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
 
-## 使用 API 扩展 Web Server
+### Hook
 
-Modern.js 提供了 **Hook** 与 **Middleware** 两类 API 来扩展 Web Server。
+Modern.js 提供的 Hook 用于控制 Web Server 中的内置逻辑，所有的页面请求都会经过 Hook。
 
-### Hook
+目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，可以用于修改渲染结果。可以在 `server/index.ts` 中这样写：
+
+```ts
+import type { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
+
+export const afterMatch: AfterMatchHook = (ctx, next) => {
+  next();
+}
+
+export const afterRender: AfterRenderHook = (ctx, next) => {
+  next();
+}
+```
 
-Hook 可以控制 Web Server 对请求处理的内置逻辑，非 BFF 请求会经过 Hook 的处理。
+项目在使用 Hook 时，应该有以下最佳实践：
 
-Hook 不可以使用运行时框架拓展。
+1. 在 afterMatch 中做权限校验。
+2. 在 afterMatch 做 Rewrite 和 Redirect。
+3. 在 afterRender 中做 HTML 内容注入。
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/hook)。
+:::note
+详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
+:::
 
 ### Middleware
 
-Middleware 可以为 Web Server 添加前置中间件，只有 SSR 请求会经过 Middleware 的处理。
+对于某些项目，可能在服务端有更多的需求，Modern.js 提供了 Middleware 为 Web Server 添加前置中间件。它只能运行在 Node 环境下，因此如果项目被部署到其他环境中，如 Worker 环境，则不可以使用 Middleware。
+
+Modern.js 默认提供了一套 API 供项目使用：
 
-Middleware 可以使用运行时框架拓展。
+```ts
+import { Middlewre } from '@modern-js/runtime/server';
 
-详细 API 可以查看 [Hook](/apis/app/runtime/web-server/middleware)。
+export const middleware = (context, next) => {
+  const { source: { req, res } } = context;
+  console.log(req.url);
+  next();
+};
+```
+
+:::note
+详细 API 和更多用法可以查看 [Middleware](/apis/app/runtime/web-server/middleware)。
+:::
+
+项目在使用 Middleware 时，应该有以下最佳实践：
+
+1. 在 Middleware 中可以直接操作原生的请求、响应对象，做数据打点、注入 SSR 渲染可能用到的 Node 服务（数据库、Redis 等）。
+2. 在 Middleware 里可以做类似功能打标、爬虫优化等功能。
+3. 在 Middleware 里可以无视后续默认渲染，自定义渲染流程。
+
+**总的来说，CSR 项目中，使用 Hook 基本能满足简单场景的所有需求。SSR 项目中，可以使用 Middleware 做更复杂的 Node 扩展。**
+
+## 通过 BFF 托管页面请求
+
+第二种方式，是利用 BFF 来托管页面渲染，这种方式下，所有的请求都会先打到 BFF 的服务。
+
+因为这种方式可以通过 BFF 统一控制所有请求的服务端逻辑。因此，它适用于服务端逻辑复杂，BFF 和页面需要公用服务端逻辑的场景。但它整体还是依托于 Modern.js 的 Web Server 运行，无法将逻辑运行在已有的服务上。
+
+使用这种方式，我们需要先通过 `pnpm new` 开启「BFF」功能。然后在配置文件中添加 [`bff.enableHandleWeb`](/configure/app/bff/enable-handle-web.html) 配置：
+
+```ts
+export default defineConfig({
+  bff: {
+    enableHandleWeb: true,
+  },
+});
+```
+
+当该值设置为 `true` 时，页面请求流量也会经过 BFF，并且 Modern.js 内置的页面渲染的逻辑默认会作为 BFF 服务的最后一个中间件运行。
 
 ## 完全自定义的 Web Server
 
 :::note
 敬请期待
-
 :::

package/zh/guides/concept/builder.mdx

@@ -6,7 +6,7 @@ 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 Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
 
 ## 构建架构