fastify-best-practiceslisted

# 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. ```js // 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 flow