@modern-js/main-doc 2.67.3 → 2.67.5

package/docs/zh/configure/app/runtime/master-app.mdx

@@ -1,8 +1,4 @@
----
-title: masterApp
----
-
-# runtime.masterApp
+# masterApp
 
 - **类型：** `Object`
 

package/docs/zh/configure/app/runtime/plugins.mdx

@@ -0,0 +1,58 @@
+# plugins
+
+- **类型：** `RuntimePlugin[]`
+- **默认值：** `[]`
+
+用于配置自定义的 Modern.js Runtime 插件。自定义 Runtime 插件的编写方式请参考 [如何编写 Runtime 插件](/plugin/introduction.html#runtime-插件)。
+
+:::info
+
+Runtime 插件需要在 `src/modern.runtime.ts` 文件中的 plugins 中进行配置。
+
+:::
+
+## 示例
+
+下面是 Runtime 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from 'my-plugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="src/modern.runtime.ts"
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import { myPlugin } from './config/plugin/myPlugin';
+
+export default defineRuntimeConfig({
+  plugins: [myPlugin({
+    foo: 1,
+    bar: 2,
+  })],
+});
+```

package/docs/zh/configure/app/usage.mdx

@@ -13,8 +13,7 @@ Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置
 
 **运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
 
-{/* TODO server 配置文件更新 */}
-**服务端运行时配置**可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中进行配置。
+**服务端运行时配置**可以在 `server/modern.server.(ts|js|mjs)` 中进行配置。
 
 ## 编译时配置
 

package/docs/zh/guides/advanced-features/_meta.json

@@ -23,5 +23,6 @@
     "label": "server-monitor",
     "collapsed": true
   },
+  "custom-server",
   "web-server"
 ]

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

@@ -0,0 +1,216 @@
+---
+sidebar_position: 16
+---
+
+# 自定义 Server
+
+Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
+
+## 自定义 Server 能力
+
+项目目录下创建 `server/modern.server.ts` 文件，可以在这个文件中添加如下配置来扩展 Server：
+- **中间件（Middleware）**
+- **渲染中间件（RenderMiddleware）**
+- **服务端插件（Plugin）**
+
+
+其中 **Plugin** 中可以定义 **Middleware** 与 **RenderMiddleware**。 中间件加载流程如下图所示：
+
+<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: [], // 插件
+});
+```
+
+
+### 类型定义
+
+`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 是不二选择。如果仅需要处理 BFF 接口路由，可以通过配置 `path` 为 BFF 的 `prefix` 来实现。
+
+:::note
+BFF 场景只有[运行时框架](/guides/advanced-features/bff/frameworks.html)为 Hono 时，BFF 路由才会经过 Middleware。
+:::
+
+#### 使用姿势
+
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+import { getMonitors } from '@modern-js/runtime';
+
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = getMonitors();
+  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();
+  // 消费服务端注入的数据
+  const message = ctx.get('message');
+
+  // ...
+};
+
+```

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

@@ -2,7 +2,11 @@
 sidebar_position: 16
 ---
 
-# 自定义 Web Server
+# 自定义 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)。
+:::
 
 Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
 
@@ -96,3 +100,172 @@ export const afterRender: AfterRenderHook = (ctx, next) => {
 :::info
 详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
 :::
+
+
+## 迁移至新版自定义 Server
+
+### 迁移背景
+
+Modern.js Server 在不断演进，为了提供更强大的功能，我们对中间件和 Server 插件的定义和使用方式进行了优化。
+虽然旧版自定义 Web Server 写法仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版的优势。
+
+### 迁移步骤
+
+1. 升级 Modern.js 版本至 x.67.5 及以上。
+2. 按照新版定义方式，在 `server/modern.server.ts` 中配置中间件或插件。
+3. 将 `server/index.ts` 自定义逻辑迁移到中间件或插件中，并参考 `Context` 和 `Next` 差异，更新您的代码。
+
+### Context 差异
+
+新版中间件 handler 类型为 Hono 的 `MiddlewareHandler`，即 `Context` 类型为 `Hono Context`。对比旧版自定义 Web Server 中 `Context` 差异如下：
+
+#### UnstableMiddleware
+
+
+```ts
+type Body = ReadableStream | ArrayBuffer | string | null;
+
+type UnstableMiddlewareContext<
+  V extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  request: Request;
+  response: Response;
+  get: Get<V>;
+  set: Set<V>;
+  // 当前匹配到的路由信息
+  route: string;
+  header: (name: string, value: string, options?: { append?: boolean }) => void;
+  status: (code: number) => void;
+  redirect: (location: string, status?: number) => Response;
+  body: (data: Body, init?: ResponseInit) => Response;
+  html: (
+    data: string | Promise<string>,
+    init?: ResponseInit,
+  ) => Response | Promise<Response>;
+};
+```
+
+UnstableMiddleware `Context` 和 Hono `Context` 的具体差异：
+
+| UnstableMiddleware       | Hono                          | 说明                                                                      |
+| :----------------------- | :---------------------------- | :------------------------------------------------------------------------ |
+| `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) 示例    |
+
+#### Middleware
+
+```ts
+type MiddlewareContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    getStatus: () => number;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+    locals: Record<string, any>;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+  source: {
+    req: IncomingMessage;
+    res: ServerResponse;
+  };
+};
+
+```
+
+Middleware `Context` 和 Hono `Context` 的具体差异：
+
+| UnstableMiddleware       | Hono                          | 说明                                                                         |
+| :----------------------- | :---------------------------- | :--------------------------------------------------------------------------- |
+| `c.request.cookie`         | `c.req.cookie()`              | 参考 [Hono Cookie Helper](https://hono.dev/docs/helpers/cookie) 文档        |
+| `c.request.pathname`       | `c.req.path`                  | 参考 [HonoRequest path](https://hono.dev/docs/api/request#path) 文档        |
+| `c.request.url`            | -                             | Hono `c.req.url` 为完整请求路径，自行通过 url 计算                             |
+| `c.request.host`           | `c.req.header('Host')`        | 通过 header 获取 host                                                       |
+| `c.request.query`          | `c.req.query()`               | 参考 [HonoRequest query](https://hono.dev/docs/api/request#query) 文档      |
+| `c.request.headers`        | `c.req.header()`              | 参考 [HonoRequest header](https://hono.dev/docs/api/request#header) 文档     |
+| `c.response.set`           | `c.res.headers.set`           | 例：`c.res.headers.set('custom-header', '1')`                               |
+| `c.response.status`        | `c.status`                    | 例：`c.status(201)`                                                         |
+| `c.response.cookies`       | `c.header`                    | 例：`c.header('Set-Cookie', 'user_id=123')`                                 |
+| `c.response.raw`           | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档          |
+
+
+#### Hook
+
+```ts
+type HookContext = {
+  response: {
+    set: (key: string, value: string) => void;
+    status: (code: number) => void;
+    getStatus: () => number;
+    cookies: {
+      set: (key: string, value: string, options?: any) => void;
+      clear: () => void;
+    };
+    raw: (
+      body: string,
+      { status, headers }: { status: number; headers: Record<string, any> },
+    ) => void;
+  };
+  request: {
+    url: string;
+    host: string;
+    pathname: string;
+    query: Record<string, any>;
+    cookie: string;
+    cookies: {
+      get: (key: string) => string;
+    };
+    headers: IncomingHttpHeaders;
+  };
+};
+
+type AfterMatchContext = HookContext & {
+  router: {
+    redirect: (url: string, status: number) => void;
+    rewrite: (entry: string) => void;
+  };
+};
+
+type AfterRenderContext = {
+  template: {
+    get: () => string;
+    set: (html: string) => void;
+    prependHead: (fragment: string) => void;
+    appendHead: (fragment: string) => void;
+    prependBody: (fragment: string) => void;
+    appendBody: (fragment: string) => void;
+  };
+};
+```
+
+Hook Context 大部分和 Middleware Context 一致，因此我们要额外关注不同 Hook 多余的部分。
+
+| UnstableMiddleware       | Hono                          | 说明                           |
+| :----------------------- | :---------------------------- | :----------------------------- |
+| `router.redirect`        | `c.redirect`                  | 参考 [Hono Context redirect](https://hono.dev/docs/api/context#redirect) 文档      |
+| `router.rewrite`         | -                             | 暂时没有提供对应的能力                                                               |
+| template API             | `c.res`                       | 参考 [Hono Context res](https://hono.dev/docs/api/context#res) 文档               |
+
+
+### Next API 差异
+
+在 Middleware 和 Hook 中，即使不执行 `next`，渲染函数也会执行。
+在新的设计中，必须执行 `next` 函数才会执行后续的 Middleware。