By using the hooks you can interact directly inside the lifecycle of Fastify. There are seven different Hooks that you can use (in order of execution):

• 'onRequest'
• 'preParsing'
• 'preValidation'
• 'preHandler'
• 'preSerialization'
• 'onError'
• 'onSend'
• 'onResponse'Example:

Or async/await

fastify.addHook('onRequest', async (request, reply) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return
})
fastify.addHook('preParsing', async (request, reply) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return
})
fastify.addHook('preValidation', async (request, reply) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return
})
fastify.addHook('preHandler', async (request, reply) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return
})
fastify.addHook('preSerialization', async (request, reply, payload) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return payload
})
fastify.addHook('onError', async (request, reply, error) => {
  // useful for custom error logging
  // you should not use this hook to update the error
})
fastify.addHook('onSend', async (request, reply, payload) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
  }
  return
})
fastify.addHook('onResponse', async (request, reply) => {
  // some code
  await asyncMethod()
  // error occurred
  if (err) {
    throw new Error('some errors occurred.')
  }
  return
})

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

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

Request and are the core Fastify objects. is the function to continue with the lifecycle.

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

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

fastify.addHook('onRequest', (request, reply, next) => {
  next(new Error('some error'))
})

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

fastify.addHook('preHandler', (request, reply, next) => {
  reply.code(400)
  next(new Error('some error'))
})

The error will be handled by .

The onError Hook

fastify.addHook('onError', (request, reply, error, next) => {
  // apm stands for Application Performance Monitoring
  apm.sendError(error)
  next()
})
// Or async
fastify.addHook('onError', async (request, reply, error) => {
  // apm stands for Application Performance Monitoring
  apm.sendError(error)
})

The preSerialization Hook

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

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

The onSend Hook

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

fastify.addHook('onSend', (request, reply, payload, next) => {
  var err = null;
  var newPayload = payload.replace('some-text', 'some-new-text')
  next(err, newPayload)
})
// Or async
fastify.addHook('onSend', async (request, reply, payload) => {
  var newPayload = payload.replace('some-text', 'some-new-text')
  return newPayload
})

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

fastify.addHook('onSend', (request, reply, payload, next) => {
  reply.code(304)
  const newPayload = null
  next(null, newPayload)
})

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

The onResponse Hook

The onResponse hook is executed when a response has been sent, so you will not be able to send more data to the client, however you can use this hook to send some data to an external service or elaborate some statistics.

If needed, you can respond to a request before you reach the route handler. An example could be an authentication hook. If you are using onRequest or preHandler use reply.send; if you are using a middleware, res.end.

fastify.addHook('onRequest', (request, reply, next) => {
  reply.send('early response')
})
// Works with async functions too
fastify.addHook('preHandler', async (request, reply) => {
  reply.send({ hello: 'world' })
})

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.

fastify.addHook('onRequest', (request, reply, next) => {
  const stream = fs.createReadStream('some-file', 'utf8')
  reply.send(stream)
})

• 'onClose'
• 'onRoute'
• 'onRegister''onClose'Triggered when fastify.close() is invoked to stop the server. It is useful when plugins need a "shutdown" event, such as a connection to a database.The first argument is the Fastify instance, the second one the done callback.

'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 do not get passed a callback.

fastify.addHook('onRoute', (routeOptions) => {
  // some code
  routeOptions.method
  routeOptions.schema
  routeOptions.url
  routeOptions.bodyLimit
  routeOptions.logLevel
  routeOptions.prefix
})

'onRegister'Triggered when a new plugin function is registered, and a new encapsulation context is created, the hook will be executed before the plugin 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.Note: This hook will not be called if a plugin is wrapped inside .

fastify.decorate('data', [])
fastify.register(async (instance, opts) => {
  instance.data.push('hello')
  console.log(instance.data) // ['hello']
    instance.data.push('world')
    console.log(instance.data) // ['hello', 'world']
  })
})
fastify.register(async (instance, opts) => {
  console.log(instance.data) // []
})
fastify.addHook('onRegister', (instance) => {
  // create a new array from the old one
  // but without keeping the reference
  // allowing the user to have encapsulated
  // instances of the `data` property
  instance.data = instance.data.slice()
})

Scope

Except for Application Hooks, all hooks are encapsulated. This means that you can decide where your hooks should run by using register as explained in the . 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.

fastify.addHook('onRequest', function (request, reply, next) {
  const self = this // Fastify context
  next()
})

Note: using an arrow function will break the binding of this to the Fastify instance.

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

Let's make an example:

fastify.addHook('onRequest', (request, reply, done) => {
  // your code
  done()
})
fastify.addHook('preParsing', (request, reply, done) => {
  // your code
  done()
})
fastify.addHook('preValidation', (request, reply, done) => {
  // your code
  done()
})
fastify.addHook('preHandler', (request, reply, done) => {
  // your code
  done()
})
fastify.addHook('preSerialization', (request, reply, done) => {
  // your code
  done()
})
fastify.route({
  method: 'GET',
  url: '/',
  schema: { ... },
  onRequest: function (request, reply, done) {
    // this hook will always be executed after the shared `onRequest` hooks
    done()
  },
  preParsing: function (request, reply, done) {
    // this hook will always be executed after the shared `preParsing` hooks
    done()
  },
  preValidation: function (request, reply, done) {
    // this hook will always be executed after the shared `preValidation` hooks
    done()
  },
  preHandler: function (request, reply, done) {
    // this hook will always be executed after the shared `preHandler` hooks
    done()
  },
  // // Example with an array. All hooks support this syntax.
  //
  // preHandler: [function (request, reply, done) {
  //   // this hook will always be executed after the shared `preHandler` hooks
  //   done()
  // }],
  preSerialization: (request, reply, payload, next) => {
    // manipulate the payload
    next(null, payload)
  },
  handler: function (request, reply) {
    reply.send({ hello: 'world' })

Note: both options also accept an array of functions.