Fastify Best Practices
A curated set of rules and patterns for building production-ready Fastify applications. Each rule includes incorrect and correct examples with explanations.
How It Works
- The agent identifies that the user is working with Fastify or asking about Fastify patterns
- The relevant rule file is loaded based on the topic (routes, validation, encapsulation, etc.)
- The agent applies the best practices from the rule when generating or reviewing code
Rules
The rules are organized by topic in the rules/ directory. Each rule follows a consistent format with impact rating, incorrect/correct examples, and references to official docs.
| Rule | File | Impact | Description |
|---|---|---|---|
| Configuration | configuration.md | HIGH | Environment config, logger setup, security options, and graceful shutdown |
| Create Server | create-server.md | LOW-MEDIUM | Use a buildServer() factory function for reusable, testable server setup |
| Create Plugin | create-plugin.md | LOW-MEDIUM | Encapsulate reusable functionality in plugins with fastify-plugin |
| Autoload | autoload.md | HIGH | Automatically load plugins and routes from the filesystem with @fastify/autoload |
| Route Best Practices | route-best-practices.md | MEDIUM | Organize routes with plugins/prefixes, use async handlers, full route options |
| Schema Validation (Zod) | schema-validation-zod.md | HIGH | Type-safe validation with Zod + fastify-type-provider-zod |
| Encapsulation | encapsulation.md | HIGH | Proper scope isolation and when to use fastify-plugin |
| Error Handling | error-handling.md | HIGH | Custom error handlers, @fastify/error, 404 handling, structured responses |
| Hooks & Lifecycle | hooks-lifecycle.md | MEDIUM | All request/reply and application hooks: onRequest, preParsing, preValidation, preHandler, preSerialization, onError, onSend, onResponse, onTimeout, onRequestAbort, onReady, onListen, onClose, onRoute, onRegister |
| Logging | logging.md | HIGH | Built-in Pino logger, request correlation, redaction, child loggers |
| Authentication | authentication.md | HIGH | JWT auth with @fastify/jwt, multi-strategy with @fastify/auth |
| Testing | testing.md | HIGH | Test with inject(), buildServer pattern, vitest/node:test |
| TypeScript | typescript-integration.md | MEDIUM | Type providers, module augmentation, typed decorators |
| Decorators | decorators.md | MEDIUM | Extend the Fastify instance, request, and reply with decorate / decorateRequest / decorateReply |
| Content Type Parser | content-type-parser.md | HIGH | Custom content type parsers, body limits, multipart uploads, catch-all and regex matching |
Usage
When generating Fastify code, read the relevant rule file(s) for the topic and apply the patterns shown. For a new project, all rules are relevant. For specific tasks, load only what's needed:
- New project setup:
create-server.md,configuration.md,autoload.md,encapsulation.md,typescript-integration.md - Adding routes:
route-best-practices.md,autoload.md,schema-validation-zod.md - Adding shared services:
create-plugin.md,autoload.md,encapsulation.md - Configuration/environment:
configuration.md - Error handling:
error-handling.md - Auth/middleware:
authentication.md,hooks-lifecycle.md,encapsulation.md - Custom decorators:
decorators.md,typescript-integration.md - Logging:
logging.md - Body parsing/file uploads:
content-type-parser.md - Writing tests:
testing.md,create-server.md
Recommended Project Structure
Using @fastify/autoload, plugins and routes are loaded automatically from their directories:
src/
plugins/ # Autoloaded — shared plugins (use fastify-plugin)
db.ts
auth.ts
config.ts
routes/ # Autoloaded — encapsulated route plugins (NO fastify-plugin)
_hooks.ts # Global route hooks (with autoHooks: true)
users/
index.ts # → /users
_hooks.ts # Hooks for /users scope only
schema.ts
posts/
index.ts # → /posts
schema.ts
server.ts # buildServer() with autoload registration
app.ts # Entry point — calls buildServer() and listen()
test/
routes/
users.test.ts
posts.test.ts
helpers.ts # createTestServer() helperPresent Results to User
When applying these best practices, mention which rule(s) you followed:
Applied Fastify best practices: - Route organization: Routes grouped by resource with prefixes - Zod validation: Request/response schemas with type inference - Encapsulation: Shared plugins usefastify-plugin, routes stay scoped - Error handling: Custom error handler with@fastify/error