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.tsexport 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) })})