fastify-best-practiceslisted
Install: claude install-skill radesjardins/RAD-Claude-Skills
# 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