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

server.ssr

  • Type: boolean
  • Default: false

Enalbe SSR configuration.

Boolean Type

When the value type is boolean, it indicates whether to enable SSR deployment mode. The default is false to disable it.

modern.config.ts
export default defineConfig({
  server: {
    ssr: true,
  },
});

Object Type

When the value type is Object, the following properties can be configured:

NameTypeDefaultDescription
modestringstringwhich defaults to using renderToString for rendering. Configure stream to enable streaming rendering
forceCSRbooleanfalsewhich is off by default for forcing CSR rendering. Configure true to force CSR by adding ?csr=true or adding x-modern-ssr-fallback header when accessing the page
disablePrerenderbooleanfasleTo ensure compatibility with the old data request method (useLoader), by default, Modern.js performs pre-rendering of components.However, if developers want to reduce one rendering when there is no use of the useLoader API in your project, you can set the configuration disablePrerender=true
unsafeHeadersstring[][]For safety reasons, Modern.js does not add excessive content to SSR_DATA. Developers can use this configuration to specify the headers that need to be injected
scriptLoadingdefer | blocking | module | asyncdeferThe configuration is the same as html.scriptLoading, supporting SSR injected script set to async loading. The priority is ssr.scriptLoading > html.scriptLoading
loaderFailureModeclientRender | errorBoundaryerrorBoundaryThe default configuration is 'errorBoundary', when an error occurs in data loader, it will default to rendering the Error component of the route. When configured as 'clientRender', if a loader throws an error, it switch to client-side rendering，you can use it with Client Loader
modern.config.ts
export default defineConfig({
  server: {
    ssr: {
      forceCSR: true,
      mode: 'stream',
      unsafeHeaders: ['User-Agent'],
      scriptLoading: 'async',
    },
  },
});

Active Fallback

In a production environment, there are scenarios where it is necessary to actively fallback an SSR project to CSR. Examples include

  1. When the SSR fails, a fallback to the CSR is required to ensure product availability.

  2. When the SSR is working normally, but there are rendering failures during csr, debugging is required.

  3. When the SSR server is under heavy load, it may be necessary to fallback some traffic directly to the CSR to avoid service downtime.

By configuring server.ssr.forceCSR to true in the project, you can control this behavior through query strings or request headers.

For example, in a custom Web Server middleware, you can actively fallback when traffic exceeds a certain threshold:

server/index.ts
export const middleware = (ctx, next) => {
  const { req, res } = ctx;
  if (condition) {
    req.headers['x-modern-ssr-fallback'] = '1';
  }

  next();
};