Plugins · Nitro

Plugins

Use plugins to extend Nitro's runtime behavior.

Plugins are auto-registered (filename ordering) and run synchronously on the first nitro initialization. They receive nitroApp context, which can be used to hook into lifecycle events.

Scanning pattern: plugins/**/*.{ts,mjs,js,cjs}

You can order the plugins by prefixing them with a number:

plugins/

  1.first.ts

  2.second.ts

Copy to clipboard

Example: Simple plugin

// plugins/test.ts

export default defineNitroPlugin((nitroApp) => {

  console.log('Nitro plugin', nitroApp)

})

Copy to clipboard

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

nitro.config.ts
nuxt.config.ts
export default defineNitroConfig({

  plugins: ['my-plugins/hello.ts']

})

Copy to clipboard
Nitro Runtime Hooks

Hooks allow extending the default runtime behaviour of Nitro by registering custom functions to the lifecycle events within plugins. (Read unjs/hookable to see how it works.)

Example:

export default defineNitroPlugin((nitro) => {

  nitro.hooks.hook("close", async () => {

    // Will run when nitro is being closed

  });

})

Copy to clipboard
Available Hooks

See the source code for list of all available runtime hooks.

"close", () => {}
"error", (error, { event? }) => {}
"render:response", (response, { event }) => {}
"request", (event) => {}
"beforeResponse", (event, { body }) => {}
"afterResponse", (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)

  });

})

Copy to clipboard
Graceful Shutdown

You can use plugins to register a hook that resolves when Nitro is closed.

export default defineNitroPlugin((nitro) => {

  nitro.hooks.hookOnce("close", async () => {

    // Will run when nitro is closed

    console.log("Closing nitro server...")

    await new Promise((resolve) => setTimeout(resolve, 500));

    console.log("Task is done!");

  });

})

Copy to clipboard
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", (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 });

  });

});

Copy to clipboard
Renderer Response

You can use plugins to register a hook that modifies the renderer response.

This only works for render handler defined with renderer and won't be called for other api/server routes. In Nuxt this hook will be called for Server Side Rendered pages
export default defineNitroPlugin((nitro) => {



  nitro.hooks.hook('render:response', (response, { event }) => {

    // Inspect or Modify the renderer response here

    console.log(response)

  })

})

Copy to clipboard
Edit this page on GitHub
Guide
Utils
Guide
TypeScript