---
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."
canonical_url: "https://nuxt.com/docs/3.x/api/kit/nitro"
---
# Nitro

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

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/`](https://nuxt.com/docs/3.x/directory-structure/shared) directory, the function must be imported from the same source file for both [`addImports`](https://nuxt.com/docs/3.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!
})
```

---

- [Source](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts)


## Sitemap

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