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

Custom Web 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.

Starting a Custom Web Server

INFO

You must ensure that the Modern.js version is x.67.5 or above.

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

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

After executing the command, a server/modern.server.ts file will be automatically created in the project directory, where you can write custom logic.

Capabilities of the Custom Web Server

In the server/modern.server.ts file, you can add the following configurations to extend the Server:

  • Middleware
  • Render Middleware
  • Server-side Plugin

In the Plugin, you can define Middleware and RenderMiddleware. The middleware loading process is illustrated in the following diagram:

Basic Configuration

server/modern.server.ts
import { defineServerConfig } from '@modern-js/server-runtime';

export default defineServerConfig({
  middlewares: [],
  renderMiddlewares: [],
  plugins: [],
});

Type Definition

defineServerConfig type definition is as follows:

import type { MiddlewareHandler } from 'hono';

type MiddlewareOrder = 'pre' | 'post' | 'default';
type MiddlewareObj = {
    name: string;
    path?: string;
    method?: 'options' | 'get' | 'post' | 'put' | 'delete' | 'patch' | 'all';
    handler: MiddlewareHandler | MiddlewareHandler[];
    before?: Array<MiddlewareObj['name']>;
    order?: MiddlewareOrder;
};
type ServerConfig = {
    middlewares?: MiddlewareObj[];
    renderMiddlewares?: MiddlewareObj[];
    plugins?: (ServerPlugin | ServerPluginLegacy)[];
}

Middleware

Middleware supports executing custom logic before and after the request handling and page routing processes in Modern.js services. If custom logic needs to handle both API routes and page routes, Middleware is the clear choice.

NOTE

If you only need to handle BFF API routes, you can determine whether a request is for a BFF API by checking if req.path starts with the BFF prefix.

Usage is as follows:

server/modern.server.ts
import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';

export const handler: MiddlewareHandler = async (c, next) => {
  const monitors = c.get('monitors');
  const start = Date.now();

  await next();

  const end = Date.now();
  // Report Duration
  monitors.timing('request_timing', end - start);
};

export default defineServerConfig({
  middlewares: [
    {
      name: 'request-timing',
      handler,
    },
  ],
});
WARNING

You must execute the next function to proceed with the subsequent Middleware.

RenderMiddleware

If you only need to handle the logic before and after page rendering, modern.js also provides rendering middleware, which can be used as follows:

server/modern.server.ts
import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';

// Inject render performance metrics
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}`);
};

// Modify the Response Body
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 supports adding the aforementioned middleware and rendering middleware for the Server in custom plugins, which can be used as follows:

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();

        // Inject server-side data for page dataLoader consumption
        middlewares?.push({
          name: 'server-plugin-middleware',
          handler: async (c, next) => {
            c.set('message', 'hi modern.js');
            await next();
            // ...
          },
        });

        // redirect
        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;
      },
    };
  },
});
server/modern.server.ts
import { defineServerConfig } from '@modern-js/server-runtime';
import serverPlugin from './plugins/serverPlugin';

export default defineServerConfig({
  plugins: [serverPlugin()],
});
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 scenario consumes data injected by the Server Side
  const message = ctx.get('message');

  // ...
};

Legacy API (Deprecated)

WARNING

The legacy API is compatible but no longer recommended. For extending server capabilities, please refer to Custom Web Server. For migration guidelines, see Migrating to the New Version of Custom Web Server.

Enable

To enable the custom Web Server feature, follow these steps:

  1. Add @modern-js/plugin-server、tsconfig-paths and ts-node to devDependencies and install them.
  2. Add server to the include section of tsconfig.
  3. Register the @modern-js/plugin-server plugin in modern.config.ts.
  4. Create a server/index.ts file in the project directory, where you can write custom logic.

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 Web 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.5 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:

UnstableMiddlewareHonoDescription
c.requestc.req.rawRefer to HonoRequest raw documentation
c.responsec.resRefer to Hono Context res documentation
c.routec.get('route')Get application context information.
loaderContext.gethonoContext.getAfter 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:

UnstableMiddlewareHonoDescription
c.request.cookiec.req.cookie()Refer to Hono Cookie Helper documentation
c.request.pathnamec.req.pathRefer to HonoRequest path documentation
c.request.url-Hono c.req.url provides the full request URL, calculate manually from URL
c.request.hostc.req.header('Host')Obtain host through header
c.request.queryc.req.query()Refer to HonoRequest query documentation
c.request.headersc.req.header()Refer to HonoRequest header documentation
c.response.setc.res.headers.setExample: c.res.headers.set('custom-header', '1')
c.response.statusc.statusExample: c.status(201)
c.response.cookiesc.headerExample: c.header('Set-Cookie', 'user_id=123')
c.response.rawc.resRefer 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.

UnstableMiddlewareHonoDescription
router.redirectc.redirectRefer to Hono Context redirect documentation
router.rewrite-No corresponding capability provided at the moment
template APIc.resRefer 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.