gil-wiki/reference/4.api/5.kit/11.nitro.md

title, description, links

title	description	links
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.	label icon to size Source i-simple-icons-github https://github.com/nuxt/nuxt/blob/main/packages/kit/src/nitro.ts 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

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

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

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'),
    })
  },
})

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

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

// @errors: 2391
import type { NitroDevEventHandler } from 'nitro/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.

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 as useRuntimeConfig. ::

Usage

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

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

Type

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

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./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

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

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

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

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

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

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'))
  },
})

export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}

::

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

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

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

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

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'))
  },
})

export function hello () {
  return 'Hello from server utils!'
}

::

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

import { defineEventHandler } from 'nitro/h3'

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