Guide
Config
Plugin
API
Tutorials
Community
Guide
Config
Plugin
API
Tutorials
Community

Custom Web Server (Not Recommended)

WARNING

Custom Web Server is compatible but no longer recommended. For extending Server capabilities, please refer to Custom Server. For migration guide, see Migrate to the New Version of Custom Server.

Modern.js encapsulates most server-side capabilities required by projects, typically eliminating the need for server-side development. However, in certain scenarios such as user authentication, request preprocessing, or adding page skeletons, custom server-side logic may still be necessary.

Modern.js provides two types of APIs to extend the Web Server: Middleware and Lifecycle Hooks.

NOTE

Middleware and Hooks only take effect when users request page routes, and BFF routes won't pass through these APIs.

Enabling Custom Web Server

Developers can execute the pnpm run new command in the project root directory to enable the "Custom Web Server" feature:

? Select operation: Create project element
? Select element type: Create "Custom Web Server" source directory

After executing the command, register the @modern-js/plugin-server plugin in modern.config.ts:

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

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

Once enabled, a server/index.ts file will be automatically created in the project directory where custom logic can be implemented.

Custom Web Server Capabilities

Unstable Middleware

Modern.js supports adding rendering middleware to the Web Server, allowing custom logic execution before and after processing page routes.

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

For detailed API and more usage, see UnstableMiddleware.

Hooks

WARNING

We recommend using UnstableMiddleware instead of Hooks.

Modern.js provides Hooks to control specific logic in the Web Server. All page requests will pass through Hooks.

Currently, two types of Hooks are available: AfterMatch and AfterRender. Developers can implement them in server/index.ts as follows:

import type {
  AfterMatchHook,
  AfterRenderHook,
} from '@modern-js/runtime/server';

export const afterMatch: AfterMatchHook = (ctx, next) => {
  next();
};

export const afterRender: AfterRenderHook = (ctx, next) => {
  next();
};

Best practices when using Hooks:

  1. Perform authorization checks in afterMatch.
  2. Handle Rewrite and Redirect in afterMatch.
  3. Inject HTML content in afterRender.
INFO

For detailed API and more usage, see Hook.

Migrate to the New Version of Custom Server

Migration Background

Modern.js Server is continuously evolving to provide more powerful features. We have optimized the definition and usage of middleware and Server plugins. While the old custom Web Server approach is still compatible, we strongly recommend migrating according to this guide to fully leverage the advantages of the new version.

Migration Steps

  1. Upgrade Modern.js version to x.67.4 or above.
  2. Configure middleware or plugins in server/modern.server.ts according to the new definition method.
  3. Migrate the custom logic in server/index.ts to middleware or plugins, and update your code with reference to the differences between Context and Next.

Context Differences

In the new version, the middleware handler type is Hono's MiddlewareHandler, meaning the Context type is Hono Context. The differences from the old custom Web Server's Context are as follows:

UnstableMiddleware

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>;
  // Current Matched Routing Information
  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>;
};

Differences between UnstableMiddleware Context and Hono Context:

UnstableMiddleware Hono Description
c.request c.req.raw Refer to HonoRequest raw documentation
c.response c.res Refer to Hono Context res documentation
c.route c.get('route') Get application context information.
loaderContext.get honoContext.get After injecting data using c.set, consume in dataLoader: the old version uses loaderContext.get, refer to the new version in Plugin example

Middleware

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;
  };
};

Differences between Middleware Context and Hono Context:

UnstableMiddleware Hono Description
c.request.cookie c.req.cookie() Refer to Hono Cookie Helper documentation
c.request.pathname c.req.path Refer to HonoRequest path documentation
c.request.url - Hono c.req.url provides the full request URL, calculate manually from URL
c.request.host c.req.header('Host') Obtain host through header
c.request.query c.req.query() Refer to HonoRequest query documentation
c.request.headers c.req.header() Refer to HonoRequest header documentation
c.response.set c.res.headers.set Example: c.res.headers.set('custom-header', '1')
c.response.status c.status Example: c.status(201)
c.response.cookies c.header Example: c.header('Set-Cookie', 'user_id=123')
c.response.raw c.res Refer to Hono Context res documentation

Hook

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 is mostly consistent with Middleware Context, so we need to pay extra attention to the additional parts of different Hooks.

UnstableMiddleware Hono Description
router.redirect c.redirect Refer to Hono Context redirect documentation
router.rewrite - No corresponding capability provided at the moment
template API c.res Refer to Hono Context res documentation

Differences in Next API

In Middleware and Hooks, the render function executes even without invoking next. In the new design, subsequent Middleware will only execute if the next function is invoked.

ON THIS PAGE