addServerPlugin requirement for imports
When using addServerPlugin, it is necessary to explicitly import definePlugin from 'nitro' within your plugin file. The same requirement applies to utilities such as useRuntimeConfig.
kit/nitro
18 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
addServerHandler function signature and parameters
addServerHandler adds a Nitro server handler. It takes a handler object with the following properties: handler (string, required) - path to event handler; route (string, optional) - path prefix or route, if empty string used as middleware; middleware (boolean, optional) - specifies this is a middleware handler, called on every route and should normally return nothing to pass to next handlers; lazy (boolean, optional) - use lazy loading to import the handler; method (string, optional) - router method matcher, if handler name contains method name it will be used as default value. The function signature is: function addServerHandler (handler: NitroEventHandler): void
addDevServerHandler function signature and parameters
addDevServerHandler adds a Nitro server handler to be used only in development mode, excluded from production build. It takes a handler object with the following properties: handler (EventHandler, required) - event handler; route (string, optional) - path prefix or route, if empty string used as middleware. The function signature is: function addDevServerHandler (handler: NitroDevEventHandler): void
useNitro function signature and constraints
useNitro returns the Nitro instance. The function signature is: function useNitro (): Nitro. It can only be called after the 'ready' hook. Changes to the Nitro instance configuration are not applied.
addServerPlugin function signature and parameters
addServerPlugin adds a plugin to extend Nitro's runtime behavior. It takes a plugin parameter (string, required) - path to the plugin file. The plugin must export a default function that accepts the Nitro instance as an argument. The function signature is: function addServerPlugin (plugin: string): void. The plugin must explicitly import definePlugin from 'nitro' and utilities such as useRuntimeConfig within the plugin file.
addPrerenderRoutes function signature and parameters
addPrerenderRoutes adds routes to be prerendered to Nitro. It takes a routes parameter (string | string[], required) - a route or an array of routes to prerender. The function signature is: function addPrerenderRoutes (routes: string | string[]): void
addServerImports function signature and parameters
addServerImports adds imports to the server, making imports available in Nitro without manual importing. It takes dirs parameter (Import | Import[], required) - an object or array of objects with properties: name (string, required) - import name to be detected; from (string, required) - module specifier to import from; priority (number, optional) - priority of import, highest priority used if multiple imports have same name; disabled (boolean, optional) - if import is disabled; meta (Record<string, any>, optional) - metadata of import; type (boolean, optional) - if import is pure type import; typeFrom (string, optional) - use as 'from' value when generating type declarations; as (string, optional) - import as this name. The function signature is: function addServerImports (dirs: Import | Import[]): void
addServerImportsDir function signature and parameters
addServerImportsDir adds a directory to be scanned for auto-imports by Nitro. It takes dirs parameter (string | string[], required) - a directory or array of directories to register to be scanned by Nitro; and opts parameter (object, optional) with prepend property (boolean, optional) - if true, directory is added to beginning of scan list. The function signature is: function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void
addServerScanDir function signature and parameters
addServerScanDir adds directories to be scanned by Nitro for subdirectories, which will be registered like the ~~/server folder. Only ~~/server/api, ~~/server/routes, ~~/server/middleware, and ~~/server/utils subdirectories are scanned. It takes dirs parameter (string | string[], required) - a directory or array of directories to register to be scanned by Nitro as server dirs; and opts parameter (object, optional) with prepend property (boolean, optional) - if true, directory is added to beginning of scan list. The function signature is: function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void
addServerHandler example with robots.txt route
Example of using addServerHandler to add a server handler from a module. The module.ts file uses addServerHandler with route '/robots.txt' and a handler at './runtime/robots.get'. The runtime/robots.get.ts file defines an event handler that returns a response with User-agent and Disallow directives. When accessing /robots.txt, it returns: User-agent: *\nDisallow: / Code: ```ts // 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 // runtime/robots.get.ts import { defineEventHandler } from 'nitro/h3' export default defineEventHandler(() => { return { body: `User-agent: *\nDisallow: /`, } }) ```
addDevServerHandler example with Tailwind config viewer
Example of using addDevServerHandler to create a server handler specifically for development purposes. This creates a Tailwind config viewer accessible at a custom route by importing tailwind-config-viewer, creating a middleware, and passing it to addDevServerHandler: ```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') 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 usage example
Example of using useNitro to access the Nitro instance after the 'ready' hook: ```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 }) }, }) ```
addServerPlugin example with hooks
Example of using addServerPlugin to add a plugin that extends Nitro's runtime behavior. The module.ts file adds the plugin from './runtime/plugin.ts'. The runtime/plugin.ts file defines a plugin that hooks into 'request' and 'response' events: ```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 example with sitemap
Example of using addPrerenderRoutes to add routes to be prerendered. This example shows a nuxt-sitemap module that conditionally adds prerender routes from a sitemap URL: ```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) } }, }) ```
addServerImports example with Storyblok
Example of using addServerImports to add imports from @storyblok/vue. Multiple named exports are added with the same name they are imported as: ```ts 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' }), ) }, }) ```
addServerImportsDir example with server composables
Example of using addServerImportsDir to add a directory for auto-imports. The module.ts file registers ./runtime/server/composables to be scanned. The runtime/server/composables/index.ts file exports a useApiSecret function that accesses runtime config. The function can then be used in server code without manual import: ```ts // 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 // runtime/server/composables/index.ts export function useApiSecret () { const { apiSecret } = useRuntimeConfig() return apiSecret } ``` ```ts // runtime/server/api/hello.ts import { defineEventHandler } from 'nitro/h3' export default defineEventHandler(() => { const apiSecret = useApiSecret() // Do something with the apiSecret }) ```
addServerScanDir example with server utils
Example of using addServerScanDir to add a directory to be scanned by Nitro. The module.ts file registers ./runtime/server to be scanned. The runtime/server/utils/index.ts file exports a hello function. The function can then be used in server code without manual import: ```ts // 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 // runtime/server/utils/index.ts export function hello () { return 'Hello from server utils!' } ``` ```ts // runtime/server/api/hello.ts import { defineEventHandler } from 'nitro/h3' export default defineEventHandler(() => { return hello() // Hello from server utils! }) ```
addServerImports constraint for shared utilities
When providing 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 with identical signature. That source file should not import anything context-specific such as Nitro context or Nuxt app context, or else it might cause errors during type-checking.