---
title: "Server Compatibility"
description: "Ship one module that serves Nuxt 4 and Nuxt 5, whichever server runtime is underneath."
canonical_url: "https://nuxt.com/docs/4.x/guide/modules/server-compatibility"
---
# Server Compatibility

> Ship one module that serves Nuxt 4 and Nuxt 5, whichever server runtime is underneath.

Nuxt supports multiple server runtimes. Nuxt 3 and 4 target Nitro v2 (`nitropack`), which uses `h3` v1; Nuxt 5 defaults to Nitro v3 (`nitro`), which uses `h3` v2. From Nuxt 4.7, an app can [opt in to Nitro v3](https://nuxt.com/docs/4.x/getting-started/upgrade#testing-nitro-v3) too, so a Nuxt 4 host does not always run Nitro v2. It is also possible to use a custom server runtime based on Web APIs, which is compatible everywhere (`nuxt/server`).

This guide covers how to write a module whose server code runs on all of them.

::note
If your module has no server code, nothing here applies.
::

## Recommended Migration

[`nuxt/server`](https://nuxt.com/docs/4.x/guide/going-further/server-imports) is the import surface for writing agnostic server code based on Web APIs, and it ships in Nuxt 4.6+. Code written with it runs on `nitropack` v2, on Nitro v3, and under other server builders, such as `@nuxt/vite-server`.

### Event Handlers

If you are registering event handlers, keep your current handler (for compatibility with Nuxt <4.6) and add a new portable one using `nuxt/server` beside it, and register both. Nuxt will register the implementation the application can run: the portable file under Nitro v3 and under other builders, the v2 file on a host still running `nitropack` v2.

```ts [module.ts]
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/my-module/status',
      handler: {
        nuxt: resolve('./runtime/server/status'),
        nitro2: resolve('./runtime/server/status.legacy'),
      },
    })
  },
})
```

The two files differ in their imports, and wherever the handler uses an h3 v1 helper or behavior that `nuxt/server` handles differently:

::code-group
```ts [runtime/server/status.ts]
import { defineEventHandler, useRuntimeConfig } from 'nuxt/server'

export default defineEventHandler(() => ({
  version: useRuntimeConfig().public.myModule.version,
}))
```

```ts [runtime/server/status.legacy.ts]
// @ts-expect-error `#imports` is typed for the app, not the server build
import { useRuntimeConfig } from '#imports'
import { defineEventHandler } from 'h3'

export default defineEventHandler(event => ({
  version: useRuntimeConfig(event).public.myModule.version,
}))
```
::

::read-more{to="https://nuxt.com/docs/4.x/getting-started/upgrade#differences-from-h3-v1"}
See every difference between h3 v1 and `nuxt/server`, and what to use instead.
::

The keys indicate which server API each file relies upon:

| Key      | The file imports                                      | Where it runs                     |
| -------- | ----------------------------------------------------- | --------------------------------- |
| `nuxt`   | `nuxt/server` only                                    | Any server builder, from Nuxt 4.6 |
| `nitro2` | `h3`, `nitropack/runtime`, `#imports`                 | `nitropack` v2                    |
| `nitro3` | `nitro`, `nitro/h3`, alone or alongside `nuxt/server` | The Nitro server builder, v3      |

Nuxt will pick the most appropriate handler to use based on the server builder a user is using. If you register a handler which the user's server builder cannot run, it will be skipped with a warning.

::tip
Use `nitro3` only for code that needs an API only Nitro v3 offers. Using `nuxt/server` will keep your code more portable in future.
::

Using this pattern means you will support both old (<4.6) and new versions of Nuxt (including Nuxt 5).

::important
The object form of `handler` needs `@nuxt/kit@^4.6` in your module's `dependencies`, which is what the [module starter](https://nuxt.com/docs/4.x/guide/modules/getting-started) sets up. If `@nuxt/kit` is only a `devDependency` and left external when you build, or is a `peerDependency`, the application's version runs instead, and a version older than 4.6 fails on the object `handler`.
::

To typecheck the `nuxt` files, install `nuxt@>=4.6` as a `devDependency`. To typecheck `nitro3` files, also install `nitro`.

If your module's own aliases already resolve to the right code on both Nitro majors, register the same file for both keys (`{ nitro2: file, nitro3: file }`) or set [`meta.compatibility.server`](#declaring-what-you-cannot-infer).

On a `nitropack` v2 host, Nuxt prefers the `nitro2` variant, so the `nuxt` variant only runs there if it is the only one registered. Test the `nuxt` variant on Nuxt 5.

In playgrounds and test fixtures on Nuxt 5, h3's auto-imported `defineEventHandler` is not available: import it from `nuxt/server`.

### Dev Server Handlers

`addDevServerHandler` takes the same keys, but each variant is a function in your module code, which runs in the Nuxt process rather than in the server build. `nuxt/server` is for [server code only](https://nuxt.com/docs/4.x/guide/going-further/server-imports#server-code-only), so don't import it from module code, even lazily.

Instead, write the handler against the web `Request` and `Response`, read configuration from `nuxt.options` in `setup`, and adapt it to each server API:

```ts [module.ts]
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'
import { defineEventHandler, toWebRequest } from 'h3'

export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup (_options, nuxt) {
    const greeting = nuxt.options.runtimeConfig.public.myModule.greeting

    function greet (request: Request) {
      const name = new URL(request.url).searchParams.get('name')
      if (!name) {
        return new Response('Missing name', { status: 400 })
      }
      return Response.json({ message: `${greeting}, ${name}!` })
    }

    addDevServerHandler({
      route: '/_my-module/greet',
      handler: {
        nuxt: event => greet(event.req),
        nitro2: defineEventHandler(event => greet(toWebRequest(event))),
      },
    })
  },
})
```

The `nuxt` variant receives a `RequestEvent` and reads its `event.req`, and the `nitro2` variant converts the h3 v1 event with `toWebRequest()`. Because the module imports `h3` v1, add `h3@^1` to your module's `dependencies`.

A dev handler's route doesn't match the same paths on every host. On a `nitropack` v2 host, every variant matches its route as a path prefix, as Nitro v2 does, so `/_my-module` also matches `/_my-module/inter.woff2`. On Nitro v3, the `nuxt` and `nitro3` variants match the route exactly.

To serve the paths below a route with every variant, end the route in `/**`:

```ts [module.ts]
addDevServerHandler({
  route: '/_my-module/assets/**',
  handler: {
    nuxt: event => serveAsset(event.req),
    nitro2: defineEventHandler(event => serveAsset(toWebRequest(event))),
  },
})
```

Here `serveAsset` takes a `Request` and returns a `Response`, like `greet` in the previous example. The route matches `/_my-module/assets` and every path below it, so you don't need to register the base path as well. On a `nitropack` v2 host, this needs `@nuxt/kit@^4.6.1` in your module's `dependencies`.

On a `nitropack` v2 host, a handler reads `event.path` relative to the base of its route, because Nitro v2 strips the base. For a request to `/_my-module/assets/inter.woff2`, `event.path` is `/inter.woff2`. The full URL is still available from `toWebRequest()`, and the `nuxt` variant reads it from `event.req.url`.

### Server Utilities

If your module exposes utilities that take the event (through an alias, `addServerImports` or a type template), type the parameter as `RequestEvent` from `nuxt/server`, or as the part it reads, such as `Pick<RequestEvent, 'req' | 'context'>`. A parameter typed as `H3Event` only accepts the event of one h3 major, so the utility can't be called from a `nuxt/server` handler.

`getNitroVersion` reports the Nitro major, not which server API the host runs: a host with a different `server.builder` runs none of the Nitro ones.

### Renderer Plugins

If your module registers render hooks, such as `render:html` to add a script to the `<head>` of every page, register a renderer plugin with `addRendererPlugin`. Every SSR renderer calls it once, before it renders, with the hooks it calls while rendering. It runs under any server builder and in whatever runtime the server renders in, including deploy targets such as Cloudflare Workers.

::code-group
```ts [module.ts]
import { addRendererPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addRendererPlugin(resolve('./runtime/server/renderer'))
  },
})
```

```ts [runtime/server/renderer.ts]
import type { RendererPlugin } from 'nuxt/server'

export default (({ hooks }) => {
  hooks.hook('render:html', (html) => {
    html.head.push('<meta name="my-module" content="enabled">')
  })
}) satisfies RendererPlugin
```
::

The plugin can register `render:route`, `render:html`, `render:html:chunk`, `render:html:close`, `render:document` and `render:island`. `render:route` and `render:html` are called for every page the renderer produces, including error pages and routes with an `ssr: false` route rule; `render:html:chunk` and `render:html:close` only for a streamed response, `render:document` only for a response that is not streamed, and `render:island` for a server component. Each is called before the same hook registered on the server runtime, such as by a Nitro plugin. The plugin is called synchronously, and a promise it returns is not awaited.

The handlers receive the request event in the same shape as a [`nuxt/server`](https://nuxt.com/docs/4.x/guide/going-further/server-imports) handler, whichever server builder runs the app: `event.req`, `event.res` and `event.url` are web-standard, and the event can be passed to the `nuxt/server` helpers. Hooks registered on the server runtime, such as by a Nitro plugin, still receive the server runtime's own event.

`render:response` is a Nitro hook rather than a renderer hook, so a renderer plugin cannot register it.

A module that processes the whole page, such as to inline critical CSS, can register `render:document`. It is called with the serialised HTML document once every `render:html` handler has run, including those registered on the server runtime, and the response is built from the `html` it leaves.

```ts [runtime/server/renderer.ts]
import type { RendererPlugin } from 'nuxt/server'

export default (({ hooks }) => {
  hooks.hook('render:document', (document) => {
    document.html = document.html.replace('</body>', '<script src="/my-module.js"></script></body>')
  })
}) satisfies RendererPlugin
```

On a version of Nuxt without renderer plugins, `addRendererPlugin` registers the same file as a Nitro plugin, which needs `@nuxt/kit` with `addRendererPlugin` in your module's `dependencies`. Nitro calls it with its app, whose `hooks` are the ones the renderer calls, so the plugin works there too as long as it only reads `hooks`, registers only hooks that version calls, does not rely on the shape of the event, and imports nothing a server of that version cannot resolve. If it does, pass the Nitro plugin to register instead:

```ts [module.ts]
addRendererPlugin({
  nuxt: resolve('./runtime/server/renderer'),
  nitro2: resolve('./runtime/server/plugin.legacy'),
})
```

A version of Nuxt without renderer plugins does not call `render:document`. There, a Nitro plugin can use the `render:response` hook, which is called with the finished document as `response.body`.

::note
A static SPA built with `@nuxt/vite-server` (`ssr: false`) has no server, so its document is rendered through the `render:html` and `render:document` hooks of renderer plugins as a prerendered route: once per build, for the base URL, with `import.meta.prerender` set. Anything the hooks add is the same for every visitor. In development, the document is rendered for each navigation. No other renderer hook is called for it.
::

### Server Plugins

Server plugins take variants too, although they are specific to Nitro so there is no generic `nuxt` variant to register. A plugin that only registers render hooks can be a [renderer plugin](#renderer-plugins) instead.

::tip
Because `definePlugin()` from `nitro` and `defineNitroPlugin()` from `nitropack/runtime` are identity functions, you may be able to replace them with a type annotation to write code that's portable for both `nitro2` and `nitro3`.
::

```ts [module.ts]
import { addNitroPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addNitroPlugin({
      nitro2: resolve('./runtime/server/plugin.legacy'),
      nitro3: resolve('./runtime/server/plugin'),
    })
  },
})
```

### Other Variants

For anything else that points at server code, such as an alias, a type template or an app plugin that reads the server event, you can use `resolveServerVariant` to resolve the variant that is appropriate for this version of Nuxt, or `undefined` if it runs none of them.

`addServerImports` accepts the same variants in `from`.

```ts [module.ts]
import { addServerImports, createResolver, defineNuxtModule, resolveServerVariant } from '@nuxt/kit'

export default defineNuxtModule({
  meta: { name: 'my-module' },
  setup (_options, nuxt) {
    const { resolve } = createResolver(import.meta.url)

    const someServerFile = resolveServerVariant({
      nuxt: resolve('./runtime/server'),
      nitro2: resolve('./runtime/server.legacy'),
    })

    if (someServerFile) {
      nuxt.options.alias['#my-module/server'] = someServerFile
    }

    addServerImports({
      name: 'verifyToken',
      from: { nuxt: resolve('./runtime/verify'), nitro2: resolve('./runtime/verify.legacy') },
    })
  },
})
```

If running with `nitropack` v2, `nitro2` will always be preferred over `nuxt`, and if running with `nitro` v3, `nitro3` will always be preferred over `nuxt`. So, if you need to test the `nuxt` variant, set `server.builder` in your test fixture to a builder that is not Nitro, such as `@nuxt/vite-server`.

### Declaring What You Cannot Infer

Nuxt reads a registered file's imports to decide which API it uses, so you don't need to declare your compatibility. But if this isn't sufficient, you can set `meta.compatibility.server`:

```ts [module.ts]
export default defineNuxtModule({
  meta: {
    name: 'my-module',
    compatibility: { server: 'nuxt' },
  },
})
```

If we can't tell, code will be treated as `nitro2`.

### Typing Runtime Config and Events

To type runtime config keys your module adds, augment `RuntimeConfig` (or `PublicRuntimeConfig`) from `nuxt/schema`. The keys are then typed in `nuxt`, `nitro2` and `nitro3` files alike.

The augmentation changes the types only. Environment variables are [cast with `destr`](https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables) (or, with `compatibilityVersion: 5`, converted to the type of the default), so declare a key with a schema in [`updateRuntimeConfig()`](https://nuxt.com/docs/4.x/api/kit/runtime-config#schemas) to have it converted to the type you augment it with.

```ts [module.ts]
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    myModule: { apiKey: string }
  }
}
```

Builder-specific types, such as `H3Event` for `useRequestEvent()` or the full Nitro config in the `nitro:config` hook, come from the generated `.nuxt/nuxt.d.ts`. Without it, they resolve to builder-agnostic types (`RequestEvent` and a reduced Nitro config). Type utilities that accept an event against `RequestEvent` to support any server builder.

### Plugins, Storage and Caching

A module built on Nitro plugins, storage or caching has no `nuxt` variant, because `nuxt/server` doesn't cover those areas. Register its files as `nitro2` now, and add a `nitro3` variant when you port them.

## Nitro-specific Code

`nuxt/server` covers request and response work: handlers, errors, router params, query and body reading and validation, headers, CORS, cookies, sessions, redirects, route rules, runtime config, app config, in-process fetch with `serverFetch()` and runtime hooks with `useServerHooks()`. But Nitro covers a lot more, so if you need any of these areas, you might need to stay on Nitro's own imports inside a `nitro2` or `nitro3` file.

Use the specifiers of the version the file is for. A file that imports `nitro/*` is read as Nitro 3 code, so a `nitro2` file must import `h3` and `nitropack/*` instead:

| Area                                                            | In a `nitro2` file                             | In a `nitro3` file                 |
| --------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------- |
| Storage: `useStorage()` and its driver configuration            | `nitropack/runtime`                            | `nitro/storage`                    |
| Caching: `defineCachedEventHandler()`, `defineCachedFunction()` | `nitropack/runtime`                            | `nitro/cache`                      |
| Server plugins                                                  | `defineNitroPlugin()` from `nitropack/runtime` | `definePlugin()` from `nitro`      |
| Nitro's own runtime hooks, such as `request` and `error`        | `useNitroApp().hooks` from `nitropack/runtime` | `useNitroHooks()` from `nitro/app` |
| Lazy handlers: `lazyEventHandler()`                             | `h3`                                           | `nitro/h3`                         |

Tasks are also not supported by `nuxt/server`.

::read-more{to="https://nuxt.com/docs/4.x/guide/going-further/server-imports#reaching-past-the-surface"}
See which h3 helpers work with the portable event, and which need Nitro-specific utilities.
::

## Notable Changes in Nitro v3

If a `nitro2` file is all you ship, it will keep running on Nitro v3 (on Nuxt 5, or on Nuxt 4.7+ when the app opts in) through the Nitro v2 compatibility layer, which is documented in the [Nuxt 5 module server compatibility guide](https://nuxt.com/docs/5.x/guide/modules/server-compatibility) along with the behaviours that changed with Nitro v3.


## Sitemap

See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.
