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:
// plugins/test.ts
export default defineNitroPlugin((nitroApp) => {
console.log('Nitro plugin', nitroApp)
})
If you have plugins in another directory, you can use the plugins
option:
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
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)
});
})
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!");
});
})
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 });
});
});
Renderer response
You can use plugins to register a hook that modifies the renderer
response.
renderer
and won't be called for other api/server routes.
In Nuxt this hook will be called for Server Side Rendered pagesexport default defineNitroPlugin((nitro) => {
nitro.hooks.hook('render:response', (response, { event }) => {
// Inspect or Modify the renderer response here
console.log(response)
})
})