By using hooks you can interact directly with the lifecycle of Fastify. There are Request/Reply hooks and application hooks:

Notice: the done callback is not available when using async/await or returning a Promise. If you do invoke a done callback in this situation unexpected behavior may occur, e.g. duplicate invocation of handlers.

and Reply are the core Fastify objects.
done is the function to continue with the .

It is easy to understand where each hook is executed by looking at the lifecycle page.
Hooks are affected by Fastify’s encapsulation, and can thus be applied to selected routes. See the section for more information.

There are eight different hooks that you can use in Request/Reply (in order of execution):

Or async/await:

  1. fastify.addHook('onRequest', async (request, reply) => {
  2.   // Some code
  3.   await asyncMethod()
  4. })

Notice: in the onRequest hook, request.body will always be null, because the body parsing happens before the hook.

preParsing

If you are using the preParsing hook, you can transform the request payload stream before it is parsed. It receives the request and reply objects as other hooks, and a stream with the current request payload.

If it returns a value (via return or via the callback function), it must return a stream.

For instance, you can uncompress the request body:

  1. fastify.addHook('preParsing', (request, reply, payload, done) => {
  2.   // Some code
  3.   done(null, newPayload)
  4. })

Or async/await:

  1. fastify.addHook('preParsing', async (request, reply, payload) => {
  2.   // Some code
  3.   await asyncMethod()
  4.   return newPayload
  5. })

Notice: in the hook, request.body will always be null, because the body parsing happens before the preValidation hook.

Notice: you should also add a receivedEncodedLength property to the returned stream. This property is used to correctly match the request payload with the Content-Length header value. Ideally, this property should be updated on each received chunk.

Notice: The old syntaxes function(request, reply, done) and async function(request, reply) for the parser are still supported but they are deprecated.

preValidation

If you are using the preValidation hook, you can change the payload before it is validated. For example:

  1. fastify.addHook('preValidation', (request, reply, done) => {
  2.   req.body = { ...req.body, importantKey: 'randomString' }
  3.   done()
  4. })

Or async/await:

  1. fastify.addHook('preValidation', async (request, reply) => {
  2.   const importantKey = await generateRandomString()
  3.   req.body = { ...req.body, importantKey }
  4. })

preHandler

  1. fastify.addHook('preHandler', (request, reply, done) => {
  2.   // some code
  3.   done()
  4. })
  1. fastify.addHook('preHandler', async (request, reply) => {
  2.   // Some code
  3.   await asyncMethod()
  4. })

preSerialization

If you are using the preSerialization hook, you can change (or replace) the payload before it is serialized. For example:

  1. fastify.addHook('preSerialization', (request, reply, payload, done) => {
  2.   const err = null
  3.   const newPayload = { wrapped: payload }
  4.   done(err, newPayload)
  5. })

Or async/await:

  1. fastify.addHook('preSerialization', async (request, reply, payload) => {
  2.   return { wrapped: payload }
  3. })

Note: the hook is NOT called if the payload is a string, a Buffer, a stream, or null.

  1. fastify.addHook('onError', (request, reply, error, done) => {
  2.   // Some code
  3.   done()
  4. })

Or async/await:

This hook is useful if you need to do some custom error logging or add some specific header in case of error.
It is not intended for changing the error, and calling reply.send will throw an exception.
This hook will be executed only after the customErrorHandler has been executed, and only if the customErrorHandler sends an error back to the user (Note that the default customErrorHandler always sends the error back to the user).
Notice: unlike the other hooks, pass an error to the done function is not supported.

onSend

If you are using the onSend hook, you can change the payload. For example:

  1. fastify.addHook('onSend', (request, reply, payload, done) => {
  2.   const err = null;
  3.   const newPayload = payload.replace('some-text', 'some-new-text')
  4.   done(err, newPayload)
  5. })

Or async/await:

  1. fastify.addHook('onSend', async (request, reply, payload) => {
  2.   const newPayload = payload.replace('some-text', 'some-new-text')
  3.   return newPayload
  4. })

You can also clear the payload to send a response with an empty body by replacing the payload with null:

  1. fastify.addHook('onSend', (request, reply, payload, done) => {
  2.   reply.code(304)
  3.   const newPayload = null
  4.   done(null, newPayload)
  5. })

Note: If you change the payload, you may only change it to a string, a Buffer, a stream, or null.

onResponse

  2. fastify.addHook('onResponse', (request, reply, done) => {
  3.   // Some code
  4.   done()
  5. })

Or async/await:

  1. fastify.addHook('onResponse', async (request, reply) => {
  2.   // Some code
  3.   await asyncMethod()
  4. })

The onResponse hook is executed when a response has been sent, so you will not be able to send more data to the client. It can however be useful for sending data to external services, for example, to gather statistics.

onTimeout

  2. fastify.addHook('onTimeout', (request, reply, done) => {
  3.   // Some code
  4.   done()
  5. })

Or async/await:

  1.   // Some code
  2.   await asyncMethod()

onTimeout is useful if you need to monitor the request timed out in your service (if the connectionTimeout property is set on the Fastify instance). The onTimeout hook is executed when a request is timed out and the HTTP socket has been hanged up. Therefore ,you will not be able to send data to the client.

Manage Errors from a hook

If you get an error during the execution of your hook, just pass it to done() and Fastify will automatically close the request and send the appropriate error code to the user.

  1. fastify.addHook('onRequest', (request, reply, done) => {
  2.   done(new Error('Some error'))
  3. })

If you want to pass a custom error code to the user, just use reply.code():

  1. fastify.addHook('preHandler', (request, reply, done) => {
  2.   reply.code(400)
  3.   done(new Error('Some error'))
  4. })

Or if you’re using async/await you can just throw an error:

  1. fastify.addHook('onResponse', async (request, reply) => {
  2.   throw new Error('Some error')
  3. })

If needed, you can respond to a request before you reach the route handler, for example when implementing an authentication hook. Replying from a hook implies that the hook chain is stopped and the rest of the hooks and handlers are not executed. If the hook is using the callback approach, i.e. it is not an async function or it returns a Promise, it is as simple as calling reply.send() and avoiding calling the callback. If the hook is async, reply.send() must be called before the function returns or the promise resolves, otherwise, the request will proceed. When reply.send() is called outside of the promise chain, it is important to return reply otherwise the request will be executed twice.

It is important to not mix callbacks and async/Promise, otherwise the hook chain will be executed twice.

If you are using onRequest or preHandler use reply.send.

If you want to respond with a stream, you should avoid using an async function for the hook. If you must use an async function, your code will need to follow the pattern in test/hooks-async.js.

  1. fastify.addHook('onRequest', (request, reply, done) => {
  2.   const stream = fs.createReadStream('some-file', 'utf8')
  3.   reply.send(stream)
  4. })

If you are sending a response without await on it, make sure to always return reply:

  1. fastify.addHook('preHandler', async (request, reply) => {
  2.   setImmediate(() => { reply.send('hello') })
  4.   // This is needed to signal the handler to wait for a response
  5.   // to be sent outside of the promise chain
  6.   return reply
  7. })
  9. fastify.addHook('preHandler', async (request, reply) => {
  10.   // the fastify-static plugin will send a file asynchronously,
  11.   // so we should return reply
  12.   reply.sendFile('myfile')
  13.   return reply
  14. })

You can hook into the application-lifecycle as well.

onReady

Triggered before the server starts listening for requests and when .ready() is invoked. It cannot change the routes or add new hooks. Registered hook functions are executed serially. Only after all onReady hook functions have completed will the server start listening for requests. Hook functions accept one argument: a callback, done, to be invoked after the hook function is complete. Hook functions are invoked with this bound to the associated Fastify instance.

  1. // callback style
  2. fastify.addHook('onReady', function (done) {
  3.   // Some code
  4.   const err = null;
  5.   done(err)
  6. })
  8. // or async/await style
  9. fastify.addHook('onReady', async function () {
  10.   // Some async code
  11.   await loadCacheFromDatabase()
  12. })

onClose

Triggered when fastify.close() is invoked to stop the server. It is useful when need a “shutdown” event, for example, to close an open connection to a database.
The first argument is the Fastify instance, the second one the done callback.

  1. fastify.addHook('onClose', (instance, done) => {
  2.   // Some code
  3.   done()
  4. })

onRoute

Triggered when a new route is registered. Listeners are passed a routeOptions object as the sole parameter. The interface is synchronous, and, as such, the listeners are not passed a callback. This hook is encapsulated.

  1. fastify.addHook('onRoute', (routeOptions) => {
  2.   //Some code
  3.   routeOptions.method
  4.   routeOptions.schema
  5.   routeOptions.url // the complete URL of the route, it will include the prefix if any
  6.   routeOptions.path // `url` alias
  7.   routeOptions.routePath // the URL of the route without the prefix
  8.   routeOptions.bodyLimit
  9.   routeOptions.logLevel
  10.   routeOptions.logSerializers
  11.   routeOptions.prefix
  12. })

If you are authoring a plugin and you need to customize application routes, like modifying the options or adding new route hooks, this is the right place.

  1. fastify.addHook('onRoute', (routeOptions) => {
  2.   function onPreSerialization(request, reply, payload, done) {
  3.     // Your code
  4.     done(null, payload)
  5.   }
  6.   // preSerialization can be an array or undefined
  7.   routeOptions.preSerialization = [...(routeOptions.preSerialization || []), onPreSerialization]
  8. })

onRegister

Triggered when a new plugin is registered and a new encapsulation context is created. The hook will be executed before the registered code.
This hook can be useful if you are developing a plugin that needs to know when a plugin context is formed, and you want to operate in that specific context, thus this hook is encapsulated.
Note: This hook will not be called if a plugin is wrapped inside fastify-plugin.

  1. fastify.decorate('data', [])
  3. fastify.register(async (instance, opts) => {
  4.   instance.data.push('hello')
  5.   console.log(instance.data) // ['hello']
  7.   instance.register(async (instance, opts) => {
  8.     instance.data.push('world')
  9.     console.log(instance.data) // ['hello', 'world']
  10.   }, { prefix: '/hola' })
  11. }, { prefix: '/ciao' })
  13. fastify.register(async (instance, opts) => {
  14.   console.log(instance.data) // []
  15. }, { prefix: '/hello' })
  17. fastify.addHook('onRegister', (instance, opts) => {
  18.   // Create a new array from the old one
  19.   // but without keeping the reference
  20.   // allowing the user to have encapsulated
  21.   // instances of the `data` property
  22.   instance.data = instance.data.slice()
  24.   // the options of the new registered instance
  25.   console.log(opts.prefix)

Except for , all hooks are encapsulated. This means that you can decide where your hooks should run by using register as explained in the plugins guide. If you pass a function, that function is bound to the right Fastify context and from there you have full access to the Fastify API.

  1. fastify.addHook('onRequest', function (request, reply, done) {
  2.   const self = this // Fastify context
  3.   done()
  4. })

Note that the Fastify context in each hook is the same as the plugin where the route was registered, for example:

  1. fastify.addHook('onRequest', async function (req, reply) {
  2.   if (req.raw.url === '/nested') {
  3.     assert.strictEqual(this.foo, 'bar')
  4.   } else {
  5.     assert.strictEqual(this.foo, undefined)
  6.   }
  8. fastify.get('/', async function (req, reply) {
  9.   assert.strictEqual(this.foo, undefined)
  10.   return { hello: 'world' }
  11. })
  13. fastify.register(async function plugin (fastify, opts) {
  14.   fastify.decorate('foo', 'bar')
  16.   fastify.get('/nested', async function (req, reply) {
  17.     assert.strictEqual(this.foo, 'bar')
  18.     return { hello: 'world' }
  19.   })
  20. })

Warn: if you declare the function with an , the this will not be Fastify, but the one of the current scope.

You can declare one or more custom lifecycle hooks (onRequest, , preParsing, , preHandler, , onSend, , and onError) hook(s) that will be unique for the route. If you do so, those hooks are always executed as the last hook in their category.
This can be useful if you need to implement authentication, where the or preValidation hooks are exactly what you need. Multiple route-level hooks can also be specified as an array.

  1. fastify.addHook('onRequest', (request, reply, done) => {
  2.   // Your code
  3.   done()
  4. })
  6. fastify.addHook('onResponse', (request, reply, done) => {
  7.   // your code
  8.   done()
  9. })
  11. fastify.addHook('preParsing', (request, reply, done) => {
  12.   // Your code
  13.   done()
  14. })
  16. fastify.addHook('preValidation', (request, reply, done) => {
  17.   // Your code
  18.   done()
  19. })
  21. fastify.addHook('preHandler', (request, reply, done) => {
  22.   // Your code
  23.   done()
  24. })
  26. fastify.addHook('preSerialization', (request, reply, payload, done) => {
  27.   // Your code
  28.   done(null, payload)
  29. })
  31. fastify.addHook('onSend', (request, reply, payload, done) => {
  32.   // Your code
  33.   done(null, payload)
  34. })
  36. fastify.addHook('onTimeout', (request, reply, done) => {
  37.   // Your code
  38.   done()
  39. })
  41. fastify.addHook('onError', (request, reply, error, done) => {
  42.   // Your code
  43.   done()
  44. })
  46. fastify.route({
  47.   method: 'GET',
  48.   url: '/',
  49.   schema: { ... },
  50.   onRequest: function (request, reply, done) {
  51.     // This hook will always be executed after the shared `onRequest` hooks
  52.     done()
  53.   },
  54.   onResponse: function (request, reply, done) {
  55.     // this hook will always be executed after the shared `onResponse` hooks
  56.     done()
  57.   },
  58.   preParsing: function (request, reply, done) {
  59.     // This hook will always be executed after the shared `preParsing` hooks
  60.     done()
  61.   },
  62.   preValidation: function (request, reply, done) {
  63.     // This hook will always be executed after the shared `preValidation` hooks
  64.     done()
  65.   },
  66.   preHandler: function (request, reply, done) {
  67.     // This hook will always be executed after the shared `preHandler` hooks
  68.     done()
  69.   },
  70.   // // Example with an array. All hooks support this syntax.
  71.   //
  72.   // preHandler: [function (request, reply, done) {
  73.   //   // This hook will always be executed after the shared `preHandler` hooks
  74.   //   done()
  75.   // }],
  76.   preSerialization: (request, reply, payload, done) => {
  77.     // This hook will always be executed after the shared `preSerialization` hooks
  78.     done(null, payload)
  79.   },
  80.   onSend: (request, reply, payload, done) => {
  81.     // This hook will always be executed after the shared `onSend` hooks
  82.     done(null, payload)
  83.   },
  84.   onTimeout: (request, reply, done) => {
  85.     // This hook will always be executed after the shared `onTimeout` hooks
  86.     done()
  87.   },
  88.   onError: (request, reply, error, done) => {
  89.     // This hook will always be executed after the shared `onError` hooks
  90.     done()
  91.   },
  92.   handler: function (request, reply) {
  93.     reply.send({ hello: 'world' })
  94. })