The Plugin System and the Boot Process

A Fastify plugin is an essential tool at the disposal of a developer. Every functionality except the root instance of the server should be wrapped in a plugin. Plugins are the key to reusability, code sharing, and achieving proper encapsulation between Fastify instances.

Fastify’s root instance will load all registered plugins asynchronously following the registration order during the boot sequence. Furthermore, a plugin can depend on others, and Fastify checks these dependencies and exits the boot sequence with an error if it finds missing ones.

This chapter starts with the declaration of a simple plugin and then, step by step, adds more layers to it. We will learn why the options parameter is crucial and how the Fastify register method uses it during the boot sequence. The final goal is to understand how plugins interact with each other thanks to encapsulation.

To understand this challenging topic, we will introduce and learn...

Technical requirements

To follow this chapter, you will need the following:

• A text editor, such as VS Code
• A working Node.js v18 installation
• Access to a shell, such as Bash or CMD

All the code examples in this chapter can be found on GitHub at https://github.com/PacktPublishing/Accelerating-Server-Side-Development-with-Fastify/tree/main/Chapter%202.

What is a plugin?

A Fastify plugin is a component that allows developers to extend and add functionalities to their server applications. Some of the most common use cases for developing a plugin are handling a database connection or extending default capabilities – for example, to request parsing or response serialization.

Thanks to their unique properties, plugins are the basic building blocks of our application. Some of the most prominent properties are the following:

• A plugin can register other plugins inside it.
• A plugin creates, by default, a new scope that inherits from the parent. This behavior also applies to its children and so on, although using the parent’s context is still possible.
• A plugin can receive an options parameter that can be used to control its behavior, construction, and reusability.
• A plugin can define scoped and prefixed routes, making it the perfect router.

At this point, it should be clear that where other frameworks...

Exploring the options parameter

This section is a deep look at the optional options parameter and how we can develop reusable plugins. A plugin declaration function isn’t anything more than a factory function that, instead of returning some new entity as factory functions usually do, adds behaviors to a Fastify instance. If we look at it like this, we can think about the options parameter as our constructor’s arguments.

Firstly, let’s recall the plugin declaration function signature:

async function myPlugin(fastify, [options])

How can we pass our custom arguments to the options parameter? It turns out that the register method has a second parameter too. So, the object we use as the argument will be passed by Fastify as Plugin’s options parameter:

app.register(myPlugin, { first: 'option'})

Now, inside the myPlugin function, we can access this value simply using options.first.

It is worth mentioning that Fastify reserves three specific...

Understanding encapsulation

So far, we’ve written a few plugins. We are pretty confident about how they are structured and what arguments a plugin receives. We still need to discuss one missing thing about them – the concept of encapsulation.

Let’s recall the plugin function definition signature:

async function myPlugin(fastify, options)

As we know at this point, the first parameter is a Fastify instance. This instance is a newly created one that inherits from the outside scope. Let’s suppose something has been added to the root instance, for example, using a decorator. In that case, it will be attached to the plugin’s Fastify instance, and it will be usable as if it is defined inside the current plugin.

The opposite isn’t true, though. If we add functionalities inside a plugin, those things will be visible only in the current plugin’s context.

Context versus scope

Firstly, let’s take a look at the definitions...

Exploring the boot sequence

We learned in the previous section that a plugin is just an asynchronous function with well-defined parameters. We’ve also seen how Fastify plugins are the core entity we use to add features and functionalities to our applications. In this section, we will learn what the boot sequence is, how plugins interact with each other, and how Fastify ensures that all the developer’s constraints are met, before running the HTTP server.

Firstly, it is essential to say that the Fastify boot sequence is asynchronous too. Fastify loads every plugin added with the register method, one by one, respecting the order of the registration. Fastify starts this process only after .listen() or .ready() are called. After that, it waits for all promises to be settled (or for all completed callbacks to be called, if the callback style is used), and then it emits the ready event. If we have already got this far, we can be sure that our application is up and running...

Handling boot and plugin errors

This section will analyze some of the most common Fastify boot errors and how we can deal with them. But what are boot errors anyway? All errors thrown during the initial load of our application, before the ready event is dispatched and the server listens for incoming connections, are called boot errors.

These errors are usually thrown when something unexpected happens during the registration of a plugin. If there are any unhandled errors during a plugin registration, Fastify, with the help of Avvio, will notify us and stop the boot process.

We can distinguish between two error types:

• Errors that we can recover from
• Errors that are not recoverable by any means

First, we will look at the most common non-recoverable error, ERR_AVVIO_PLUGIN_TIMEOUT, which usually means we forgot to tell Fastify to continue with the boot process.

Then, we will learn about the tools Fastify gives us to recover from other kinds of errors. It is...

Summary

In this chapter, we learned about the importance of plugins and how the Fastify boot process works. Everything in Fastify can and really should be put in a plugin. It is the base building block of scalable and maintainable applications, thanks to encapsulation and a predictable loading order. Furthermore, we can use fastify-plugin to control the default encapsulation and manage dependencies between plugins.

We learned how our applications are nothing more than a bunch of Fastify plugins that work together. Some are used to encapsulate routers, using prefixes to namespace them. Others are used to add core functionalities, such as connections to databases or some other external systems. In addition to that, we can install and use core and community plugins directly from npm.

Moreover, we covered the boot process’s asynchronous nature and how every step can be awaited if needed. It is guaranteed that if any error is encountered during the loading of plugins, the boot...