> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# server.ssr

- **Type:** `boolean` | `Object`
- **Default:** `false`

Enable 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.

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

### Object Type

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

| Name                   | Type                            | Default         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mode                   | `string`                        | `stream`        | which defaults to using streaming rendering. Configure `string` to use `renderToString` for rendering                                                                                                                                                                                                                                                                                                                                                                                  |
| forceCSR               | `boolean`                       | `false`         | which 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                                                                                                                                                                                                                                                                                                                |
| unsafeHeaders          | `string[]`                      | `[]`            | 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                                                                                                                                                                                                                                                                                                                       |
| loaderFailureMode      | `clientRender \| errorBoundary` | `errorBoundary` | The default configuration is `'errorBoundary'`, when an error occurs in [data loader](/guides/basic-features/data/data-fetch.md#data-loader-recommended), it will default to rendering the [`Error`](/guides/basic-features/routes/routes.md#error-handling) 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](/guides/basic-features/data/data-fetch.md#client-loader) |
| moduleFederationAppSSR | `boolean`                       | `false`         | Enables app-level Module Federation SSR contract handshake. Enable this in both host and remote apps when using app-level MF SSR                                                                                                                                                                                                                                                                                                                                                       |

```ts title="modern.config.ts"
export default defineConfig({
  server: {
    ssr: {
      forceCSR: true,
      mode: 'stream',
      unsafeHeaders: ['User-Agent'],
      moduleFederationAppSSR: true,
    },
  },
});
```

### 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:

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

export const handler: MiddlewareHandler = async (c, next) => {
  if (condition) {
    c.set('forceCSR', '1');
  }
  await next();
};

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