指南
配置
插件
API
教程
社区
指南
配置
插件
API
教程
社区
简体中文

自定义 Web Server

Modern.js 将大部分项目需要的服务端能力都进行了封装，通常项目无需进行服务端开发。但在有些开发场景下，例如用户鉴权、请求预处理、添加页面渲染骨架等，项目仍需要对服务端进行定制。

Modern.js 提供了 渲染中间件（Middleware） 与生命周期钩子（Hook） 两类 API 来扩展 Web Server。

NOTE

Middleware 与 Hook 只会在用户请求页面路由时生效，BFF 路由不会经过这些 API。

开启自定义 Web Server

开发者可以在项目根目录执行 pnpm run new 命令，开启「自定义 Web Server」功能：

? 请选择你想要的操作 创建工程元素
? 请选择创建元素类型 新建「自定义 Web Server」源码目录

执行命令后，在 modern.config.ts 中注册 @modern-js/plugin-server 插件:

modern.config.ts
import { serverPlugin } from '@modern-js/plugin-server';

export default defineConfig({
  plugins: [..., serverPlugin()],
});

开启功能后，项目目录下会自动创建 server/index.ts 文件，可以在这个文件中编写自定义逻辑。

自定义 Web Server 能力

Unstable Middleware

Modern.js 支持为 Web Server 添加渲染中间件，支持在处理页面路由的前后执行自定义逻辑。

server/index.ts
import {
  UnstableMiddleware,
  UnstableMiddlewareContext,
} from '@modern-js/runtime/server';

const time: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
  const start = Date.now();

  await next();

  const end = Date.now();

  console.log(`dur=${end - start}`);
};

export const unstableMiddleware: UnstableMiddleware[] = [time];
INFO

详细 API 和更多用法查看 UnstableMiddleware。

Hook

WARNING

我们推荐使用 UnstableMiddleware 代替 Hook。

Modern.js 提供的 Hook 用于控制 Web Server 中的特定逻辑，所有的页面请求都会经过 Hook。

目前提供了两种 Hook，分别是 AfterMatch 和 AfterRender，开发者可以在 server/index.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 时，应该有以下最佳实践：

  1. 在 afterMatch 中做权限校验。
  2. 在 afterMatch 做 Rewrite 和 Redirect。
  3. 在 afterRender 中做 HTML 内容注入。
INFO

详细 API 和更多用法可以查看 Hook。