Plugins

Nitro plugins will be executed once during server startup in order to allow extending Nitro's runtime behavior. They receive nitroApp context, which can be used to hook into Nitro lifecycle events.

Plugins are auto-registered from plugins/ directory and run synchronously (by order of file name) on the first Nitro initialization.

Example:

export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro plugin', nitroApp)
})

If you have plugins in another directory, you can use the plugins option:

import { defineNitroConfig } from "nitro/config";

export default defineNitroConfig({
  plugins: ['my-plugins/hello.ts']
})

Nitro runtime hooks

You can use Nitro hooks to extend the default runtime behaviour of Nitro by registering custom (async or sync) functions to the lifecycle events within plugins.

Example:

export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook("close", async () => {
    // Will run when nitro is being closed
  });
})

Available hooks

• "request", (event) => {}
• "error", (error, { event? }) => {}
• "response", (event, { body }) => {}

Examples

Capturing errors

You can use plugins to capture all application errors.

export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook("error", async (error, { event }) => {
    console.error(`${event.path} Application error:`, error)
  });
})

Graceful shutdown

Server will gracefully shutdown and wait for any background pending tasks initiated by event.waitUntil

Request and response lifecycle

You can use plugins to register a hook that can run on request lifecycle:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook("request", (req) => {
    console.log("on request", req.url);
  });
});