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
Example: Simple plugin
// 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
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
});
})
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.
export default defineNitroPlugin((nitro) => {
nitro.hooks.hook('render:response', (response, { event }) => {
// Inspect or Modify the renderer response here
console.log(response)
})
})