fastify-best-practices

Fastify: Core Architecture & Best Practices

Core Mental Model — The Plugin Tree

Understand that a Fastify application is a directed acyclic graph (DAG) of encapsulated contexts, not a flat middleware chain. Every call to fastify.register() creates a new child node in this tree. The root Fastify instance is the only context that is not itself a plugin.

The DAG is managed internally by the avvio library. Avvio guarantees deterministic, async loading in the exact order plugins are registered. Never rely on timing assumptions — rely on registration order.

Plugins signal readiness in exactly one of two ways: by returning a Promise, or by calling the done callback. Never mix both in the same plugin. If the plugin function is async, never accept or call done — Fastify will await the returned Promise. If the function is synchronous, call done() when setup is complete.

// CORRECT: async plugin — no done parameter
module.exports = async function myPlugin(fastify, opts) {
  // setup logic
}

// CORRECT: callback plugin — call done explicitly
module.exports = function myPlugin(fastify, opts, done) {
  // setup logic
  done()
}

// WRONG: mixing async and done — causes hangs or double-resolution
module.exports = async function myPlugin(fastify, opts, done) {
  await someSetup()
  done() // BUG: never do this in an async function
}

Encapsulation Rules — Hard Invariants

These five rules are non-negotiable. Every architectural decision in Fastify flows from them:

1. Child inherits everything from parent and ancestors. A plugin registered inside another plugin sees all decorators, hooks, and parsers from its parent chain up to root.

2. Siblings are completely isolated. Two plugins registered at the same level share nothing with each other. Plugin A cannot see Plugin B's decorators, routes, or hooks, even if they are registered on the same parent.

3. Parents cannot access child entities. A parent context never sees decorators, hooks, or routes added by its children. Data flows downward only.