fastify-best-practices

Fastify 5 Best Practices

Table of Contents

• Request lifecycle
• Top anti-patterns
• Quick patterns
• Reference files

<quick_reference>

Request lifecycle (exact order)

Incoming Request
  └─ Routing
      └─ onRequest hooks
          └─ preParsing hooks
              └─ Content-Type Parsing
                  └─ preValidation hooks
                      └─ Schema Validation (→ 400 on failure)
                          └─ preHandler hooks
                              └─ Route Handler
                                  └─ preSerialization hooks
                                      └─ onSend hooks
                                          └─ Response Sent
                                              └─ onResponse hooks

Error at any stage → onError hooks → error handler → onSend → response → onResponse.

</quick_reference>

<anti_patterns>

Top anti-patterns

1. Mixing async/callback in handlers — Use async OR callbacks, never both. With async, return the value; don't call reply.send() AND return.

2. Returning undefined from async handler — Fastify treats this as "no response yet". Return the data or call reply.send().

3. Using arrow functions when you need this — Arrow functions don't bind this to the Fastify instance. Use function declarations for handlers that need this.

4. Forgetting fastify-plugin wrapper — Without it, decorators/hooks stay scoped to the child context. Parent and sibling plugins won't see them.

5. Decorating with reference types directly — decorateRequest('data', {}) shares the SAME object across all requests. Use null initial + onRequest hook to assign per-request.

6. Sending response in onError hook — onError is read-only for logging. Use setErrorHandler() to modify error responses.

7. Not handling reply.send() in async hooks — Call return reply after reply.send() in async hooks to prevent "Reply already sent" errors.