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
import { createResolver, defineNuxtModule, addServerHandler } 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.
import { createResolver, defineNuxtModule, addServerHandler } from '@nuxt/kit'
export default defineNuxtModule({
setup(options) {
const { resolve } = createResolver(import.meta.url)
addServerHandler({
route: '/robots.txt',
handler: resolve('./runtime/robots.get')
})
}
})
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 'h3'
import { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
export default defineNuxtModule({
setup() {
addDevServerHandler({
handler: defineEventHandler(() => {
return {
body: `Response generated at ${new Date().toISOString()}`
}
}),
route: '/_handler'
})
}
})
Type
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 { defineNuxtModule, addDevServerHandler } from '@nuxt/kit'
export default defineNuxtModule({
async setup(options, nuxt) {
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.
useNitro()
only after ready
hook.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.
Usage
import { createResolver, defineNuxtModule, addServerPlugin } 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
import { createResolver, defineNuxtModule, addServerPlugin } from '@nuxt/kit'
export default defineNuxtModule({
setup() {
const { resolve } = createResolver(import.meta.url)
addServerPlugin(resolve('./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
import { defineNuxtModule, addPrerenderRoutes } 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[] | true | A route or an array of routes to prerender. |
addServerImportsDir
Add a directory to be scanned for auto-imports by Nitro.
Usage
import { defineNuxtModule, createResolver, addServerImportsDir } 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[] | 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.
import { defineNuxtModule, createResolver, addServerImportsDir } 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:
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.
~/server/api
, ~/server/routes
, ~/server/middleware
, and ~/server/utils
are scanned.Usage
import { defineNuxtModule, createResolver, addServerScanDir } 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[] | 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.
import { defineNuxtModule, createResolver, addServerScanDir } 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.
export default defineEventHandler(() => {
return hello() // Hello from server utils!
})
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.