Advanced Fastify: Hooks, Middleware, and Decorators

In the first article of this series, we introduced Fastify and compared it to Express, highlighting the benefits of switching to Fastify for high-performance web applications. We also explored Fastify's plugin system in detail, showing you how to extend and customize your web applications with reusable modules.

In this part, we'll dive deeper into some of Fastify's more advanced concepts. Specifically, we'll demonstrate how to use hooks, middleware, decorators, and validation to build more robust web applications. We'll also briefly touch on some viable strategies for migrating an existing Express application to Fastify.

Let's get started!

Hooks and Middleware in Fastify

Hooks in Fastify allow you to listen for specific events in your application's lifecycle and perform specific tasks when those events occur. Hooks are analogous to Express-style middleware functions but are more performant, allowing you to perform tasks such as authentication, logging, routing, data parsing, error handling, and more. There are two types of hooks in Fastify: request/reply hooks and application hooks.

Request/Reply Hooks in Fastify

Request/reply hooks are executed during a server's request/reply cycle, allowing you to perform various tasks before or after an incoming request or outgoing response is processed. These hooks can be applied to all routes or a selection of routes. They are typically used to implement features such as:

• Access control
• Data validation
• Request logging

And more.

Examples of request/reply hooks include preRequest, onSend, onTimeout, and others.

Here's an example that uses the onSend hook to add a Server header to all responses sent from a server:

fastify.addHook("onSend", (request, reply, payload, done) => {
  reply.headers({
    Server: "fastify",
  });

  done();
});

The request and reply objects should be familiar to you by now, and the payload parameter represents the response body. You can modify the response payload here or clear it altogether by setting it to null in the hook function. Finally, the done() callback should be executed to signify the end of the hook so that the request/reply lifecycle continues. It can take up to two arguments: an error (if any), or null, and the updated payload.

With the above code in place, each response will now contain the specified headers:

curl -I http://localhost:3000

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
server: fastify
content-length: 12
Date: Sun, 12 Feb 2023 18:23:40 GMT
Connection: keep-alive
Keep-Alive: timeout=72

If you want to implement hooks for a subset of routes, you need to create a new encapsulation context and then register the hook on the fastify instance in the plugin. For example, you can create another onSend hook in the health plugin we demonstrated earlier in this tutorial:

// plugin.js
function health(fastify, options, next) {
  fastify.get("/health", (request, reply) => {
    reply.send({ status: "up" });
  });

  fastify.addHook("onSend", (request, reply, payload, done) => {
    const newPlayload = payload.replace("up", "down");
    reply.headers({
      "Cache-Control": "no-store",
      Server: "nodejs",
    });

    done(null, newPlayload);
  });

  next();
}

export default health;

This time, the onSend hook is used to modify the response body for all the routes in the plugin context (just /health, in this case) by changing up to down, and it also overrides the Server response header from the parent context while adding a new Cache-Control header. Hence, requests to the /health route will now produce the following response:

curl -i http://localhost:3000/health

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
cache-control: no-store
server: nodejs
content-length: 17
Date: Sun, 12 Feb 2023 18:54:21 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"down"}⏎

Note that the onSend hook in the health context will run after all shared onSend hooks. If you want to register a hook on a specific route instead of all the routes in the plugin context, you can add it to the route options as shown below:

function health(fastify, options, next) {
  fastify.get(
    "/health",
    {
      onSend: function (request, reply, payload, done) {
        const newPlayload = payload.replace("up", "down");
        reply.headers({
          "Cache-Control": "no-store",
          Server: "nodejs",
        });

        done(null, newPlayload);
      },
    },
    (request, reply) => {
      reply.send({ status: "up" });
    }
  );

  fastify.get("/health/alwaysUp", (request, reply) => {
    reply.send({ status: "up" });
  });

  next();
}

export default health;

The onSend hook has been moved to the route options for the /health route, so it only affects the request/response cycle for this route. You can observe the difference by making requests to /health and /health/alwaysUp as shown below. Even though they are in the same plugin context with identical handlers, the content of their responses is different.

GET /health:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
server: nodejs
cache-control: no-store
content-length: 17
Date: Sun, 12 Feb 2023 19:08:37 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"down"}

GET /health/alwaysUp:

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
server: fastify
content-length: 15
Date: Sun, 12 Feb 2023 19:09:18 GMT
Connection: keep-alive
Keep-Alive: timeout=72

{"status":"up"}

Fastify Application Hooks

Application hooks, on the other hand, are executed outside of the request/reply lifecycle. They are executed upon events emitted by the Fastify instance and can be used to carry out general server or plugin tasks, such as:

• Connecting to databases and other resources
• Loading or unloading configuration
• Closing connections
• Persisting data
• Flushing logs

And others.

Here's an example that simulates a graceful shutdown using Fastify's onClose application hook. Such a setup is ideal if you are deploying an update or your server needs to restart for other reasons.

fastify.addHook("onClose", (instance, done) => {
  instance.log.info("Server is shutting down...");
  // Perform any necessary cleanup tasks here
  done();
});

process.on("SIGINT", () => {
  fastify.close(() => {
    fastify.log.info("Server has been shut down");
    process.exit(0);
  });
});

In this example, the onClose hook is registered on the server's root context, and the callback is executed before the server is shut down. The hook function has access to the current Fastify instance and a done callback, which should be called when the hook is finished.

In addition, the process.on() function listens for the SIGINT signal, which is sent to the process when you press CTRL+C or the system shuts down. When the signal is received, the fastify.close() function is called to shut down the server, and a record of the server closure is logged to the console.

After adding the above code to your program, start the server and press Ctrl-C to shut down the process. You will observe the following logs in the console:

{"level":30,"time":1676240333903,"pid":615734,"hostname":"fedora","msg":"Server is shutting down..."}
{"level":30,"time":1676240333903,"pid":615734,"hostname":"fedora","msg":"Server has been shut down"}

Middleware in Fastify

Fastify also supports Express-style middleware but it requires you to install an external plugin such as @fastify/express or @fastify/middie. This eases migration from Express to Fastify, but it should not be used in greenfield projects in favor of hooks. Note that in many cases, you can find a native Fastify plugin that provides the same functionality as Express middleware.

The example below demonstrates how to use a standard Express middleware such as cookie-parser in Fastify, but you should prefer native alternatives — such as @fastify/cookie — where possible, since they are better optimized for use in Fastify.

import Fastify from "fastify";
import middie from "@fastify/middie";
import cookieParser from "cookie-parser";

const fastify = Fastify({
  logger: true,
});

await fastify.register(middie);

fastify.use(cookieParser());

fastify.get("/", function (request, reply) {
  console.log("Cookies: ", request.raw.cookies);
  reply.send("Hello world!");
});

const port = process.env.PORT || 3000;

fastify.listen({ port }, function (err, address) {
  if (err) {
    fastify.log.error(err);
    process.exit(1);
  }

  fastify.log.info(`Fastify is listening on port: ${address}`);
});

Once the @fastify/middie plugin is imported and registered, you can begin to use Express middleware via the use() method provided on the Fastify instance, and it should just work as shown above. Note that every single middleware applied in this manner will be executed on the onRequest hook phase.

Decorators in Fastify

Decorators are a feature that allow you to customize core objects with any type of JavaScript property, such as functions, objects, or any primitive type. For example, you can use decorators to store custom data or register a new method in the Fastify, Request, or Reply objects through the decorate(), decorateRequest(), and decorateReply() methods, respectively.

This example demonstrates using Fastify's decorators to add
functionality to a web application:

import Fastify from 'fastify';
import fastifyCookie from '@fastify/cookie';

const fastify = Fastify({
  logger: true,
});

await fastify.register(fastifyCookie, {
  secret: 'secret',
});

fastify.decorate('authorize', authorize);
fastify.decorate('getUser', getUser);
fastify.decorateRequest('user', null);

async function getUser(token) {
  // imagine the token is used to retrieve a user
  return {
    id: 1234,
    name: 'John Doe',
    email: 'john@example.com',
  };
}

async function authorize(request, reply) {
  const { user_token } = request.cookies;
  if (!user_token) {
    throw new Error('unauthorized: missing session cookie');
  }

  const cookie = request.unsignCookie(user_token);
  if (!cookie.valid) {
    throw new Error('unauthorized: invalid cookie signature');
  }

  let user;
  try {
    user = await fastify.getUser(cookie.value);
  } catch (err) {
    request.log.warn(err);
    throw err;
  }

  request.user = user;
}

fastify.get('/', async function (request, reply) {
  await this.authorize(request, reply);

  reply.send(`Hello ${request.user.name}!`);
});

. . .

The above snippet of code decorates two functions on the fastify instance. The first one is getUser() — it takes a token as a parameter and returns a user object (hardcoded in this example).

The authorize() function is defined next. It checks whether the user_token cookie is present in the request and validates it. If the cookie is invalid or missing, an error is thrown. Otherwise, the cookie value is used to retrieve the corresponding user with the getUser() function, and the result is stored in a user property on the request object. If an error occurs while retrieving the user, the error is logged and re-thrown.

While you can add any property to Fastify, Request, or Reply objects, you need to declare them in advance with decorators. This helps the underlying JavaScript engine to optimize handling of these objects.

curl --cookie "user_token=yes.Y7pzW5FUVuoPD5yXLV8joDdR35gNiZJzITWeURHF5Tg" http://127.0.0.1:3000/

Hello John Doe!

Data Validation in Fastify

Data validation is an essential feature of any web application that relies on client data, as it helps to prevent security vulnerabilities caused by malicious payloads and improves the reliability and robustness of an application.

Fastify uses JSON schema to define the validation rules for each route's input payload, which includes the request body, query string, parameters, and headers. The JSON schema is a standard format for defining the structure and constraints of JSON data, and Fastify uses Ajv, one of the fastest and most efficient JSON schema validators available.

To use JSON validation in Fastify, you need to define a schema for each route that expects a payload. You can specify the schema using the standard JSON schema format or the Fastify JSON schema format, which is a more concise and expressive way of expressing the schema.

Here's an example of how to define a JSON schema for a route in Fastify:

const bodySchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number" },
    email: { type: "string", format: "email" },
  },
  required: ["name", "email"],
};

fastify.post(
  "/users",
  {
    schema: {
      body: bodySchema,
    },
  },
  async (request, reply) => {
    const { name, age, email } = request.body;
    reply.send({
      name,
      age,
      email,
    });
  }
);

In this example, we define a schema that expects an object with three properties: name, age, and email. The name property should be a string, the age property should be a number, and the email property should be a string in email format. We also specify that name and email are required properties.

When a client sends a POST request to /users with an invalid payload, Fastify automatically returns a '400 Bad Request' response with an error message indicating which property failed the validation. However, if the payload adheres to the schema, the route handler function will be executed with the parsed payload as request.body.

Here's an example of a request with an invalid payload (the email key is in the wrong format):

curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name":"John","age": 44,"email":"john@example"}' \
  http://localhost:3000/users

And here's the response produced by Fastify:

{"statusCode":400,"error":"Bad Request","message":"body/email must match format \"email\""}⏎

See the docs to learn more about validation in Fastify and how to customize its behavior to suit your needs.

Planning an Incremental Migration from Express to Fastify

Incremental migration is an excellent strategy for those who want to switch to a new framework but cannot afford to make the change all at once. By adopting an incremental approach, you can gradually introduce Fastify into your project while still using Express, giving you time to make any necessary changes and ensure a smooth transition.

The first step is to identify the parts of your project that would benefit most from Fastify's features, such as its built-in support for validation and logging, and improved performance over Express. Once you have identified those areas, you can introduce Fastify alongside your existing Express code.

This might involve setting up a separate server instance that handles certain routes or endpoints using Fastify while still using Express for the rest of an application. But you'll probably find it easier to use the @fastify/express plugin to add full Express compatibility to Fastify so that you can use Express middleware and applications as if they are Fastify plugins.

To use the @fastify/express plugin, you can install it via npm and register it with your Fastify instance:

import Fastify from "fastify";
import expressPlugin from "@fastify/express";

const fastify = Fastify({
  logger: true,
});

await fastify.register(expressPlugin);

You can then use Express middleware or applications just like in an Express application. For example:

import express from "express";
const expressApp = express();

expressApp.use((req, res, next) => {
  console.log("This is an Express middleware");
  next();
});

expressApp.get("/express", (req, res) => {
  res.json({ body: "hello from express" });
});

fastify.use(expressApp);

curl http://localhost:3000/express

{ "body": "hello from express" }

As you become more comfortable with Fastify, you can start to migrate more and more of your code over, eventually replacing all of your Express-specific code with Fastify. By taking the time to plan and execute a thoughtful migration strategy, you can ensure a smooth transition and ultimately end up with a more efficient, high-performing application.

Up Next: Migrate to Fastify from Express

We've covered a lot of ground in this tutorial. We hope you've gained a deeper understanding of how Fastify's novel features like hooks and decorators can help you customize and extend your applications more than Express.

In the next and final part of this series, we'll provide a practical guide for migrating to Fastify from Express. We'll cover common migration scenarios, provide tips for optimizing performance and improving security, and share some best practices along the way.

Thanks for reading, and see you next time!

P.S. If you liked this post, subscribe to our JavaScript Sorcery list for a monthly deep dive into more magical JavaScript tips and tricks.

P.P.S. If you need an APM for your Node.js app, go and check out the AppSignal APM for Node.js.