---
title: "Nitro"
description: Nuxt Kit provides a set of utilities to help you work with Nitro. These functions allow you to add server handlers, plugins, and prerender routes.
links:
  - label: Source
    icon: i-simple-icons-github
    to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts
    size: xs
---

Nitro is an open source TypeScript framework to build ultra-fast web servers. Nuxt uses Nitro as its server engine. You can use `useNitro` to access the Nitro instance, `addServerHandler` to add a server handler, `addDevServerHandler` to add a server handler to be used only in development mode, `addServerPlugin` to add a plugin to extend Nitro's runtime behavior, and `addPrerenderRoutes` to add routes to be prerendered by Nitro.

## `addServerHandler`

Adds a Nitro server handler. Use this if you want to create server middleware or a custom route.

### Usage

```ts twoslash
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

### Type

```ts
function addServerHandler (handler: NitroEventHandler): void
```

### Parameters

**handler**: A handler object with the following properties:

| Property     | Type      | Required | Description                                                                                                                                   |
|--------------|-----------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `handler`    | `string`  | `true`   | Path to event handler.                                                                                                                        |
| `route`      | `string`  | `false`  | Path prefix or route. If an empty string used, will be used as a middleware.                                                                  |
| `middleware` | `boolean` | `false`  | Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers. |
| `lazy`       | `boolean` | `false`  | Use lazy loading to import the handler. This is useful when you only want to load the handler on demand.                                      |
| `method`     | `string`  | `false`  | Router method matcher. If handler name contains method name, it will be used as a default value.                                              |

### Examples

#### Basic Usage

You can use `addServerHandler` to add a server handler from your module.

::code-group

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

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

```ts twoslash [runtime/robots.get.ts]
export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})
```

::

When you access `/robots.txt`, it will return the following response:

```txt
User-agent: *
Disallow: /
```

## `addDevServerHandler`

Adds a Nitro server handler to be used only in development mode. This handler will be excluded from production build.

### Usage

```ts twoslash
import { defineEventHandler } from 'h3'
import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addDevServerHandler({
      handler: defineEventHandler(() => {
        return {
          body: `Response generated at ${new Date().toISOString()}`,
        }
      }),
      route: '/_handler',
    })
  },
})
```

### Type

```ts twoslash
// @errors: 2391
import type { NitroDevEventHandler } from 'nitropack/types'
// ---cut---
function addDevServerHandler (handler: NitroDevEventHandler): void
```

### Parameters

**handler**: A handler object with the following properties:

| Property  | Type           | Required | Description                                                                  |
|-----------|----------------|----------|------------------------------------------------------------------------------|
| `handler` | `EventHandler` | `true`   | Event handler.                                                               |
| `route`   | `string`       | `false`  | Path prefix or route. If an empty string used, will be used as a middleware. |

### Examples

#### Basic Usage

In some cases, you may want to create a server handler specifically for development purposes, such as a Tailwind config viewer.

```ts
import { joinURL } from 'ufo'
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (options, nuxt) {
    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')

    // @ts-expect-error - tailwind-config-viewer does not have correct types
    const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
    const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()

    addDevServerHandler({ route, handler: viewerDevMiddleware })
  },
})
```

## `useNitro`

Returns the Nitro instance.

::warning
You can call `useNitro()` only after `ready` hook.
::

::note
Changes to the Nitro instance configuration are not applied.
::

### Usage

```ts
import { defineNuxtModule, useNitro } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // Do something with Nitro instance
    })
  },
})
```

### Type

```ts
function useNitro (): Nitro
```

## `addServerPlugin`

Add plugin to extend Nitro's runtime behavior.

::tip
You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).
::

::warning
It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.
::

### Usage

```ts twoslash
import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

### Type

```ts
function addServerPlugin (plugin: string): void
```

### Parameters

| Property | Type     | Required | Description                                                                                                   |
|----------|----------|----------|---------------------------------------------------------------------------------------------------------------|
| `plugin` | `string` | `true`   | Path to the plugin. The plugin must export a default function that accepts the Nitro instance as an argument. |

### Examples

::code-group

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

```ts [runtime/plugin.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('on request', event.path)
  })

  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
    console.log('on response', event.path, { body })
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log('on after response', event.path, { body })
  })
})
```

::

## `addPrerenderRoutes`

Add routes to be prerendered to Nitro.

### Usage

```ts
import { addPrerenderRoutes, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-sitemap',
    configKey: 'sitemap',
  },
  defaults: {
    sitemapUrl: '/sitemap.xml',
    prerender: true,
  },
  setup (options) {
    if (options.prerender) {
      addPrerenderRoutes(options.sitemapUrl)
    }
  },
})
```

### Type

```ts
function addPrerenderRoutes (routes: string | string[]): void
```

### Parameters

| Property | Type                            | Required | Description                                 |
|----------|---------------------------------|----------|---------------------------------------------|
| `routes` | `string \| string[]`{lang="ts"} | `true`   | A route or an array of routes to prerender. |

## `addServerImports`

Add imports to the server. It makes your imports available in Nitro without the need to import them manually.

::warning
If you want to provide a utility that works in both server and client contexts and is usable in the [`shared/`](/docs/4.x/directory-structure/shared) directory, the function must be imported from the same source file for both [`addImports`](/docs/4.x/api/kit/autoimports#addimports) and `addServerImports` and should have identical signature. That source file should not import anything context-specific (i.e., Nitro context, Nuxt app context) or else it might cause errors during type-checking.
::

### Usage

```ts twoslash
import { addServerImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addServerImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})
```

### Type

```ts
function addServerImports (dirs: Import | Import[]): void
```

### Parameters

`imports`: An object or an array of objects with the following properties:

| Property   | Type                  | Required | Description                                                                                                     |
|------------|-----------------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `name`     | `string`              | `true`   | Import name to be detected.                                                                                     |
| `from`     | `string`              | `true`   | Module specifier to import from.                                                                                |
| `priority` | `number`              | `false`  | Priority of the import; if multiple imports have the same name, the one with the highest priority will be used. |
| `disabled` | `boolean`             | `false`  | If this import is disabled.                                                                                     |
| `meta`     | `Record<string, any>` | `false`  | Metadata of the import.                                                                                         |
| `type`     | `boolean`             | `false`  | If this import is a pure type import.                                                                           |
| `typeFrom` | `string`              | `false`  | Use this as the `from` value when generating type declarations.                                                 |
| `as`       | `string`              | `false`  | Import as this name.                                                                                            |

## `addServerImportsDir`

Add a directory to be scanned for auto-imports by Nitro.

### Usage

```ts twoslash
import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

### Type

```ts
function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### Parameters

| Property | Type                            | Required | Description                                                                                                         |
|----------|---------------------------------|----------|---------------------------------------------------------------------------------------------------------------------|
| `dirs`   | `string \| string[]`{lang="ts"} | `true`   | A directory or an array of directories to register to be scanned by Nitro.                                          |
| `opts`   | `{ prepend?: boolean }`         | `false`  | Options for the import directory. If `prepend` is `true`, the directory is added to the beginning of the scan list. |

### Examples

You can use `addServerImportsDir` to add a directory to be scanned by Nitro. This is useful when you want Nitro to auto-import functions from a custom server directory.

::code-group

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

```ts twoslash [runtime/server/composables/index.ts]
export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}
```

::

You can then use the `useApiSecret` function in your server code:

```ts twoslash [runtime/server/api/hello.ts]
const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // Do something with the apiSecret
})
```

## `addServerScanDir`

Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered
just like the `~~/server` folder is.

::note
Only `~~/server/api`, `~~/server/routes`, `~~/server/middleware`, and `~~/server/utils` are scanned.
::

### Usage

```ts twoslash
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

### Type

```ts
function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### Parameters

| Property | Type                            | Required | Description                                                                                                         |
|----------|---------------------------------|----------|---------------------------------------------------------------------------------------------------------------------|
| `dirs`   | `string \| string[]`{lang="ts"} | `true`   | A directory or an array of directories to register to be scanned for by Nitro as server dirs.                       |
| `opts`   | `{ prepend?: boolean }`         | `false`  | Options for the import directory. If `prepend` is `true`, the directory is added to the beginning of the scan list. |

### Examples

You can use `addServerScanDir` to add a directory to be scanned by Nitro. This is useful when you want to add a custom server directory.

::code-group

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

```ts twoslash [runtime/server/utils/index.ts]
export function hello () {
  return 'Hello from server utils!'
}
```
::

You can then use the `hello` function in your server code.

```ts twoslash [runtime/server/api/hello.ts]
function hello () {
  return 'Hello from server utils!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})
```