npm - @modern-js/main-doc - Versions diffs - 2.67.4 → 2.67.6 - Mend

@modern-js/main-doc 2.67.4 → 2.67.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (198) hide show

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

@@ -6,34 +6,226 @@ sidebar_position: 16
 Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。
-Modern.js 提供了 **渲染中间件（Middleware）** 与**生命周期钩子（Hook）** 两类 API 来扩展 Web Server。
+## 开启自定义 Web Server
+:::info
+必须确保 Modern.js 版本是 x.67.5 及以上。
+:::
+开启自定义 Web Server 功能，需要执行以下步骤：
+1. devDependencies 增加 `@modern-js/server-runtime` 及 `ts-node`依赖并安装。
+2. `tsconfig` 的 `include` 中添加 `server`。
+3. 项目目录下创建 `server/modern.server.ts` 文件，可以在这个文件中编写自定义逻辑。
+## 自定义 Web 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 是不二选择。
 :::note
-Middleware 与 Hook 只会在用户请求页面路由时生效，BFF 路由不会经过这些 API。
+如果仅需要处理 BFF 接口路由，可以通过检查 `req.path` 是否以 BFF `prefix` 开头，来判断是否为 BFF 接口请求。
 :::
-## 开启自定义 Web Server
+使用姿势如下：
+```ts title="server/modern.server.ts"
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
-开发者可以在项目根目录执行 `pnpm run new` 命令，开启「自定义 Web Server」功能：
+export const handler: MiddlewareHandler = async (c, next) => {
+  const monitors = c.get('monitors');
+  const start = Date.now();
+  await next();
-```bash
-? 请选择你想要的操作 创建工程元素
-? 请选择创建元素类型 新建「自定义 Web Server」源码目录
+  const end = Date.now();
+  // 上报耗时
+  monitors.timing('request_timing', end - start);
+};
+export default defineServerConfig({
+  middlewares: [
+    {
+      name: 'request-timing',
+      handler,
+    },
+  ],
+});
 ```
-执行命令后，在 `modern.config.ts` 中注册 `@modern-js/plugin-server` 插件:
+:::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();
-```ts title="modern.config.ts"
-import { serverPlugin } from '@modern-js/plugin-server';
+  const { res } = c;
+  const text = await res.text();
+  const newText = text.replace('<body>', '<body> <h3>bytedance</h3>');
-export default defineConfig({
-  plugins: [..., serverPlugin()],
+  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,
+    },
+  ],
 });
 ```
-开启功能后，项目目录下会自动创建 `server/index.ts` 文件，可以在这个文件中编写自定义逻辑。
-## 自定义 Web Server 能力
+### 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();
+  // SSR 场景消费服务端注入的数据
+  const message = ctx.get('message');
+  // ...
+};
+```
+## 旧版 API（废弃）
+:::warning
+旧版 API 兼容但不再推荐使用，扩展 Server 能力请移步 [自定义 Web Server](/guides/advanced-features/web-server.html)，迁移指南参考 [迁移至新版自定义 Web Server](/guides/advanced-features/web-server.html#迁移至新版自定义-web-server)。
+:::
 ### Unstable Middleware
@@ -64,10 +256,6 @@ export const unstableMiddleware: UnstableMiddleware[] = [time];
 ### Hook
-:::warning
-我们推荐使用 UnstableMiddleware 代替 Hook。
-:::
 Modern.js 提供的 Hook 用于控制 Web Server 中的特定逻辑，所有的页面请求都会经过 Hook。
 目前提供了两种 Hook，分别是 `AfterMatch` 和 `AfterRender`，开发者可以在 `server/index.ts` 中这样写：
@@ -96,3 +284,172 @@ export const afterRender: AfterRenderHook = (ctx, next) => {
 :::info
 详细 API 和更多用法可以查看 [Hook](/apis/app/runtime/web-server/hook)。
 :::
+## 迁移至新版自定义 Web Server
+### 迁移背景
+Modern.js Server 在不断演进，为了提供更强大的功能，我们对中间件和 Server 插件的定义和使用方式进行了优化。
+虽然旧版 API 仍被兼容，但我们强烈建议您按照本指南进行迁移，以充分利用新版的优势。
+### 迁移步骤
+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/web-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/guides/basic-features/deploy.mdx CHANGED Viewed

@@ -110,7 +110,6 @@ Netlify 是一个流行的 Web 开发平台，专为构建、发布和维护现
 :::info
 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 :::
 在 Netlify 平台上添加项目，部署即可。
@@ -197,6 +196,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 ### 纯前端项目
 在当前项目的根目录添加 `vercel.json` 文件：
 ```bash
 ./
 ├── src
@@ -206,6 +206,7 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 ```
 在 `vercel.json` 中添加以下内容：
 ```json title="vercel.json"
 {
   "buildCommand": "modern deploy",
@@ -219,7 +220,6 @@ Vercel 是一个面向现代 Web 应用的部署平台，它提供了丰富的
 :::info
 你可参考部署[项目示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
 :::
 ### 全栈项目
@@ -314,6 +314,7 @@ Github Pages 支持两种部署方式，通过分支部署或通过 Github Actio
 4. 执行 `npm run deploy:gh-pages`。
 :::info
 1. 执行 `MODERNJS_DEPLOY=ghPages modern deploy`，Modern.js 会把可用于 github 部署的产物构建到 `.output` 目录。
 2. 可以参考项目[示例](https://github.com/web-infra-dev/modern-js-examples/tree/main/examples/modern-js-deploy-csr)。
@@ -393,7 +394,7 @@ Nginx 是一个高性能的 HTTP 和反向代理服务器，它可以处理静
 如果你的项目是纯前端项目，也可以通过 Nginx 来部署应用，以下提供一个 Nginx 配置的示例来演示如何托管一个纯前端项目的产物。
-```conf title="nginx.conf"
+```nginx title="nginx.conf"
 # user [user] [group];
 worker_processes 1;

package/docs/zh/guides/basic-features/output-files.mdx CHANGED Viewed

@@ -96,34 +96,6 @@ dist
     └── qux.[hash].mp4
 ```
-## Node.js 产物目录
-当你在 Modern.js 中开启了 SSR 或 SSG 等服务端功能时，Modern.js 会在构建后生成一份 Node.js 产物，并输出到 `bundles` 目录下：
-```bash
-dist
-├── bundles
-│   └── [name].js
-├── static
-└── html
-```
-Node.js 产物通常只包含 JS 文件，不包含 HTML、CSS 等文件。此外，Node 产物的 JS 文件名称也不会自动生成哈希值。
-你可以通过 [output.distPath.server](/configure/app/output/dist-path) 配置项来修改 Node 产物的输出路径。
-比如，将 Node.js 产物输出到 `server` 目录：
-```ts
-export default {
-  output: {
-    distPath: {
-      server: 'server',
-    },
-  },
-};
-```
 ## 扁平化产物目录
 有时候你不想产物目录有太多层级，可以将目录设置为空字符串，使生成的产物目录扁平化。

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

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

package/docs/zh/plugin/runtime-plugins/api.mdx CHANGED Viewed

@@ -2,6 +2,12 @@
 Modern.js 的 Runtime 插件允许您在应用程序的 React 代码运行时扩展和修改其行为。通过 Runtime 插件，您可以轻松地执行初始化任务、实现 React 高阶组件（HOC）封装等功能。
+:::info
+Runtime 插件需要通过 `src/modern.runtime.ts` 中的 [`plugins`](/configure/app/runtime/plugins) 字段配置。
+:::
 ## 插件结构
 一个典型的 Runtime 插件如下所示：
@@ -151,16 +157,35 @@ await hooks.onBeforeRender.call(myContext);
 您可以组合使用多个钩子来实现更复杂的功能。例如，您可以使用 `onBeforeRender` 获取数据，然后使用 `wrapRoot` 将数据通过 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/zh/tutorials/first-app/c04-routes.mdx CHANGED Viewed

@@ -118,8 +118,9 @@ import { Radio } from 'antd';
 然后将 UI 最顶部进行修改，增加一组单选框
-```tsx {4-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   return (
     <div>
       <div className="h-16 p-2 flex items-center justify-center">
@@ -146,8 +147,9 @@ import { Outlet, useLocation, useNavigate } from '@modern-js/runtime/router';
 最后在 Layout 组件里增加局部状态和相关逻辑：
-```tsx {2-9}
+```tsx
 export default function Layout() {
+  // [!code highlight:8]
   const navigate = useNavigate();
   const location = useLocation();
   const [currentList, setList] = useState(location.pathname || '/');

package/docs/zh/tutorials/first-app/c05-loader.mdx CHANGED Viewed

@@ -56,11 +56,13 @@ Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以
 Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
-```tsx {1,2,5,13}
+```tsx
+// [!code highlight:2]
 import { useLoaderData } from '@modern-js/runtime/router';
 import type { LoaderData } from './page.data';
 function Index() {
+  // [!code highlight:1]
   const { data } = useLoaderData() as LoaderData;
   return (
@@ -68,6 +70,7 @@ function Index() {
       <Helmet>
         <title>All</title>
       </Helmet>
+      // [!code highlight:1]
       <List
         dataSource={data}
         renderItem={info => <Item key={info.name} info={info} />}

package/package.json CHANGED Viewed

@@ -15,17 +15,20 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.67.4",
+  "version": "2.67.6",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.4.1",
-    "@modern-js/sandpack-react": "2.67.4"
+    "@modern-js/sandpack-react": "2.67.6"
   },
   "devDependencies": {
-    "@rspress/shared": "1.43.11",
+    "@rsbuild/plugin-sass": "1.3.1",
+    "@shikijs/transformers": "^3.4.2",
+    "@rspress/shared": "2.0.0-beta.6",
+    "@rspress/plugin-llms": "2.0.0-beta.6",
     "@types/fs-extra": "9.0.13",
     "@types/node": "^16",
     "classnames": "^2.5.1",
@@ -33,7 +36,7 @@
     "fs-extra": "^10",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "rspress": "1.43.11",
+    "rspress": "2.0.0-beta.6",
     "ts-node": "^10.9.1",
     "typescript": "^5"
   },