Nitro

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:

Example#

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]
import { defineEventHandler } from 'nitro/h3'

export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})

::

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

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 'nitro/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 'nitro/types'
// ---cut---
function addDevServerHandler (handler: NitroDevEventHandler): void

Parameters#

handler: A handler object with the following properties:

Example#

Basic Usage#

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

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#

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#

function useNitro (): Nitro

addServerPlugin#

Add plugin to extend Nitro's runtime behavior.

::tip You can read more about Nitro plugins in the Nitro documentation. ::

::warning It is necessary to explicitly import definePlugin from ` within your plugin file. The same requirement applies to utilities such asuseRuntimeConfig`. ::

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#

Example#

::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]
import { definePlugin } from 'nitro'

export default definePlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('on request', event.req.url)
  })

  nitroApp.hooks.hook('response', async (res) => {
    console.log('on response', await res.text())
  })
})

::

addPrerenderRoutes#

Add routes to be prerendered to Nitro.

Usage#

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#

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

Parameters#

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/ directory, the function must be imported from the same source file for both 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:

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#

Example#

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] import { defineEventHandler } from 'nitro/h3'

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#

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

Parameters#

Example#

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] import { defineEventHandler } from 'nitro/h3'

function hello () { return 'Hello from server utils!' } // ---cut--- export default defineEventHandler(() => { return hello() // Hello from server utils! }) ```