@modern-js/main-doc 2.67.4 → 2.67.5

package/docs/en/plugin/cli-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 This document details the API for Modern.js CLI plugins. CLI plugins allow you to extend and customize the functionality of Modern.js projects during the build and development process.
 
+:::info
+
+CLI plugins need to be configured via the [`plugins`](/configure/app/plugins) field in `modern.config.ts`.
+
+:::
+
 ## Plugin Basic Structure
 
 A typical CLI plugin structure is as follows:

package/docs/en/plugin/runtime-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 Modern.js's Runtime Plugins allow you to extend and modify the behavior of your application during its React code execution.  With Runtime Plugins, you can easily perform initialization tasks, implement React Higher-Order Component (HOC) wrapping, and more.
 
+:::info
+
+Runtime plugins need to be configured via the [`plugins`](/configure/app/runtime/plugins) field in `src/modern.runtime.ts`.
+
+:::
+
 ## Plugin Structure
 
 A typical Runtime Plugin looks like this:
@@ -150,16 +156,35 @@ Allows you to wrap the application's root component with a custom React componen
 You can combine multiple hooks to implement more complex functionality. For example, you can use `onBeforeRender` to fetch data and then use `wrapRoot` to pass the data to the entire application via Context:
 
 ```ts
-api.onBeforeRender(async (context) => {
-  const data = await fetchData(context.req);
-  context.data = data;
-});
-
-api.wrapRoot((App) => {
-  return (props) => (
-    <DataContext.Provider value={props.data}>
-      <App {...props} />
-    </DataContext.Provider>
-  );
-});
+import { RuntimePluginFuture, RuntimeReactContext } from '@modern-js/runtime';
+import { useContext, createContext } from 'react';
+
+export const ThemeContext = createContext<{ theme: string } | null>(null);
+
+export const themePlugin = (): RuntimePluginFuture => {
+  return {
+    name: 'theme-plugin',
+    setup: api => {
+      api.onBeforeRender(async context => {
+        const userPreference = await fetch('/api/user/theme-settings').then(
+          res => res.json(),
+        );
+        context.data = {
+          theme: userPreference.theme,
+        };
+      });
+
+      api.wrapRoot(App => {
+        return props => {
+          const context = useContext(RuntimeReactContext);
+          return (
+            <ThemeContext.Provider value={context.data}>
+              <App {...props} />
+            </ThemeContext.Provider>
+          );
+        };
+      });
+    },
+  };
+};
 ```

package/docs/en/tutorials/first-app/c05-loader.mdx

@@ -7,7 +7,7 @@ In the previous chapter, we learned how to add client route.
 
 In this chapter, we will learn how to add **Loader** to the routing component.
 
-By far, we have provided data to components through hardcoding. If you want to get data from the remote, you usually use `useEffect` to do it. But when SSR is enabled, `useEffect` will not be executed at the server level, so this SSR can only render a very limited UI.
+So far, we have provided data to components through hardcoding. If you want to get data from the remote, you usually use `useEffect` to do it. But when SSR is enabled, `useEffect` will not be executed at the server level, so this SSR can only render a very limited UI.
 
 Modern.js provides the ability of Data Loader to support homogeneous data acquisition in components to maximize the value of SSR.
 

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

@@ -1,39 +1,18 @@
----
-sidebar_position: 9
----
-
 # plugins
 
 - **类型：** `CliPlugin[]`
 - **默认值：** `[]`
 
-用于配置自定义的 Modern.js 框架插件。
-
-自定义插件的编写方式请参考 [如何编写插件](/plugin/plugin-system)。
+用于配置自定义的 Modern.js 框架 CLI 插件。自定义 CLI 插件的编写方式请参考 [如何编写 CLI 插件](/plugin/introduction.html#cli-插件)。
 
 ## 注意事项
 
-该选项**用于配置框架插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+该选项**用于配置框架 CLI 插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
 
 - 配置 Rsbuild 插件，请使用 [builderPlugins](/configure/app/builder-plugins) 配置项。
 - 配置 Rspack 或 webpack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
 - 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
-
-## 插件类型
-
-Modern.js 中内置了三种不同的框架插件：
-
-- `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
-- `Server 插件`，适用于服务端。
-- `Runtime 插件`，适用于前端运行时。
-
-目前 Modern.js 开放了自定义 CLI 插件的能力，Server 插件和 Runtime 插件会在后续开放。
-
-## 插件执行顺序
-
-默认情况下，自定义插件会按照 `plugins` 数组的顺序依次执行，Modern.js 内置插件的执行时机早于自定义插件。
-
-当插件内部使用了控制顺序的相关字段，比如 `pre`、`post` 时，会基于声明的字段对执行顺序进行调整，详见 [插件结构](/plugin/plugin-system)。
+- 配置框架 Runtime 插件，请使用 [runtime 配置文件 plugins](/configure/app/runtime/plugins) 配置项。
 
 ## 示例
 

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,7 +13,7 @@ Modern.js 不支持同时在 `package.json` 中和 `modern.config.ts` 中配置
 
 **运行时配置**可以在 `src/modern.runtime.(ts|js|mjs)` 文件中配置。
 
-**服务端运行时配置**可以在根路径下的 `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。

package/docs/zh/plugin/cli-plugins/api.mdx

@@ -2,6 +2,12 @@
 
 本文档详细介绍了 Modern.js CLI 插件的 API。CLI 插件允许您在 Modern.js 项目的构建和开发过程中扩展和定制功能。
 
+:::info
+
+CLI 插件需要通过 `modern.config.ts` 中的 [`plugins`](/configure/app/plugins) 字段配置。
+
+:::
+
 ## 插件基础结构
 
 一个典型的 CLI 插件结构如下：