Nitro · Nuxt Kit

Nitro is an open source TypeScript framework to build ultra-fast web servers. Nuxt 3 (and, optionally, Nuxt Bridge) 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 it if you want to create server middleware or custom route.

Type

function addServerHandler (handler: NitroEventHandler): voidexport interface NitroEventHandler {  handler: string;  route?: string;  middleware?: boolean;  lazy?: boolean;  method?: string;}

Parameters

`handler`

Type: NitroEventHandler

Required: true

A handler object with the following properties:

handler (required)
Type: string
Path to event handler.
route (optional)
Type: string
Path prefix or route. If an empty string used, will be used as a middleware.
middleware (optional)
Type: boolean
Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers.
lazy (optional)
Type: boolean
Use lazy loading to import handler.
method (optional)
Type: string
Router method matcher. If handler name contains method name, it will be used as a default value.

Examples

// https://github.com/nuxt-modules/robotsimport { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'export default defineNuxtModule({  setup(options) {    const resolver = createResolver(import.meta.url)    addServerHandler({      route: '/robots.txt'      handler: resolver.resolve('./runtime/robots.get.ts')    })  }})

`addDevServerHandler`

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

Type

function addDevServerHandler (handler: NitroEventHandler): voidexport interface NitroEventHandler {  handler: string;  route?: string;  middleware?: boolean;  lazy?: boolean;  method?: string;}

Parameters

`handler`

Type: NitroEventHandler

Required: true

A handler object with the following properties:

handler (required)
Type: string
Path to event handler.
route (optional)
Type: string
Path prefix or route. If an empty string used, will be used as a middleware.
middleware (optional)
Type: boolean
Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers.
lazy (optional)
Type: boolean
Use lazy loading to import handler.
method (optional)
Type: string
Router method matcher.

Examples

import { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'export default defineNuxtModule({  setup() {    const resolver = createResolver(import.meta.url)    addDevServerHandler({      handler: resolver.resolve('./runtime/uptime.get'),      route: '/_handler'    })  }})

// https://github.com/nuxt-modules/tailwindcssimport { joinURL } from 'ufo'import { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'export default defineNuxtModule({  async setup(options) {    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')    // @ts-ignore    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.

You can call useNitro() only after ready hook.

Changes to the Nitro instance configuration are not applied.

Type

function useNitro (): Nitroexport interface Nitro {  options: NitroOptions;  scannedHandlers: NitroEventHandler[];  vfs: Record<string, string>;  hooks: Hookable<NitroHooks>;  unimport?: Unimport;  logger: ConsolaInstance;  storage: Storage;  close: () => Promise<void>;  updateConfig: (config: NitroDynamicConfig) => void | Promise<void>;}

Examples

// https://github.com/nuxt/nuxt/blob/4e05650cde31ca73be4d14b1f0d23c7854008749/packages/nuxt/src/core/nuxt.ts#L404import { defineNuxtModule, useNitro, addPlugin, createResolver } from '@nuxt/kit'export default defineNuxtModule({  setup(options, nuxt) {    const resolver = createResolver(import.meta.url)    nuxt.hook('ready', () => {      const nitro = useNitro()      if (nitro.options.static && nuxt.options.experimental.payloadExtraction === undefined) {        console.warn('Using experimental payload extraction for full-static output. You can opt-out by setting `experimental.payloadExtraction` to `false`.')        nuxt.options.experimental.payloadExtraction = true      }      nitro.options.replace['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)      nitro.options._config.replace!['process.env.NUXT_PAYLOAD_EXTRACTION'] = String(!!nuxt.options.experimental.payloadExtraction)      if (!nuxt.options.dev && nuxt.options.experimental.payloadExtraction) {        addPlugin(resolver.resolve(nuxt.options.appDir, 'plugins/payload.client'))      }    })  }})

`addServerPlugin`

Add plugin to extend Nitro's runtime behavior.

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

Type

function addServerPlugin (plugin: string): void

Parameters

`plugin`

Type: string

Required: true

Path to the plugin. The plugin must export a function that accepts Nitro instance as an argument.

Examples

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

`addPrerenderRoutes`

Add routes to be prerendered to Nitro.

Type

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

Parameters

`routes`

Type: string | string[]

Required: true

A route or an array of routes to prerender.

Examples

import { defineNuxtModule, prerenderRoutes } from '@nuxt/kit'export default defineNuxtModule({  meta: {    name: 'nuxt-sitemap',    configKey: 'sitemap',  },  defaults: {    sitemapUrl: '/sitemap.xml',    prerender: true,  },  setup(options) {    if (options.prerender) {      prerenderRoutes(options.sitemapUrl)    }  }})

Templates

Nuxt Kit provides a set of utilities to help you work with templates. These functions allow you to generate extra files during development and build time.

Resolving

Nuxt Kit provides a set of utilities to help you resolve paths. These functions allow you to resolve paths relative to the current module, with unknown name or extension.