api-framework-fastify

API Development with Fastify

Quick Guide: Use Fastify for high-performance Node.js REST APIs with built-in JSON Schema validation and powerful plugin encapsulation. Use @fastify/type-provider-typebox for end-to-end type safety (both Type and TypeBoxTypeProvider re-exported from it). Wrap shared plugins with fastify-plugin to expose decorators. Always define response schemas for serialization performance and data leak prevention.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST use withTypeProvider<>() for type-safe request/response handling)

(You MUST wrap shared plugins with fastify-plugin to expose decorators to parent scope)

(You MUST define response schemas to enable fast-json-stringify optimization)

(You MUST use named constants for HTTP status codes - never raw numbers)

</critical_requirements>

Auto-detection: Fastify, fastify.register, fastify.decorate, fastify-plugin, TypeBox, @fastify/type-provider-typebox, @fastify/type-provider-json-schema-to-ts, fastify-type-provider-zod, preHandler, onRequest, preSerialization, JSON Schema validation, fast-json-stringify, FastifyPluginAsyncTypebox

When to use:

• Building high-performance REST APIs (45k+ req/sec benchmarks)
• Need schema-based validation with automatic coercion
• Want plugin encapsulation for modular architecture
• Require lifecycle hooks for cross-cutting concerns
• Building APIs with strict TypeScript type safety requirements

When NOT to use:

• Simple internal APIs without performance requirements (consider your existing solution)
• GraphQL APIs (use dedicated GraphQL servers)
• Edge/serverless with size constraints (Fastify has larger footprint than minimal frameworks)
• When middleware ecosystem compatibility with Express is required

Key patterns covered:

• Server setup with TypeScript type providers
• Plugin system and encapsulation patterns
• JSON Schema validation for request/response
• Lifecycle hooks (onRequest, preHandler, onSend, etc.)
• Decorators for extending Fastify/Request/Reply
• Error handling with setErrorHandler
• Route organization with prefix patterns

Detailed Resources:

• [examples/core.md](examples/core.md) - Server setup, routes, schemas, error handling, testing
• [examples/plugins.md](examples/plugins.md) - Plugin system, encapsulation, decorators
• [examples/schemas.md](examples/schemas.md) - TypeBox schemas, validation, type-safe routes
• [examples/hooks.md](examples/hooks.md) - Lifecycle hooks and cross-cutting concerns
• [reference.md](reference.md) - Decision frameworks, anti-patterns, quick reference

<philosophy>

Philosophy

Schema-first, compiled validation. Fastify compiles JSON schemas at startup into highly optimized validator functions. This provides both runtime safety and documentation from a single source of truth.

Plugin encapsulation creates microservices in a monolith. Each plugin has its own scope for decorators and hooks. Child plugins inherit from parents, but parents cannot access child resources - enabling clean separation of concerns.

Performance without sacrifice. Fastify achieves 2-3x throughput over Express while maintaining developer ergonomics through TypeScript integration and comprehensive hook system.

</philosophy>

<patterns>

Core Patterns

Pattern 1: Server Setup with Type Provider

Configure Fastify with TypeBox for compile-time AND runtime type safety. Type is re-exported from @fastify/type-provider-typebox.

import Fastify from "fastify";
import { Type, TypeBoxTypeProvider } from "@fastify/type-provider-typebox";

const SERVER_PORT = 3000;
const SERVER_HOST = "0.0.0.0";

const buildServer = () => {
  const server = Fastify({
    logger: { level: process.env.LOG_LEVEL ?? "info" },
  }).withTypeProvider<TypeBoxTypeProvider>();

  server.setErrorHandler(errorHandler);
  server.register(userRoutes, { prefix: "/api/users" });

  return server;
};

export { buildServer };

Why good: TypeBox provider enables type inference from schemas, factory function enables testing, Type imported from same package

Full example with startup, error handling, and testing: [examples/core.md](examples/core.md)

Pattern 2: Schema Definition with TypeBox

Define schemas that provide both TypeScript types AND runtime validation from a single source.

import { Type, Static } from "@fastify/type-provider-typebox";

const MIN_USERNAME_LENGTH = 3;
const MAX_USERNAME_LENGTH = 50;

export const UserSchema = Type.Object({
  id: Type.String({ format: "uuid" }),
  username: Type.String({
    minLength: MIN_USERNAME_LENGTH,
    maxLength: MAX_USERNAME_LENGTH,
  }),
  email: Type.String({ format: "email" }),
});

// Derive TypeScript types from schemas
export type User = Static<typeof UserSchema>;

Why good: Single source of truth for types and validation, Static<> derives TS types automatically

Full schema patterns (composition, partial updates, reusable components): [examples/schemas.md](examples/schemas.md)

Pattern 3: Route Definition with Full Schema

Define routes with request AND response schemas for complete type safety and serialization optimization.

import type { FastifyPluginAsync } from "fastify";
import { Type } from "@fastify/type-provider-typebox";

const HTTP_OK = 200;
const HTTP_NOT_FOUND = 404;

export const userRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.get(
    "/:id",
    {
      schema: {
        params: UserParamsSchema,
        response: {
          [HTTP_OK]: UserSchema,
          [HTTP_NOT_FOUND]: ErrorSchema,
        },
      },
    },
    async (request, reply) => {
      const user = await fastify.userService.findById(request.params.id);
      if (!user) {
        return reply.status(HTTP_NOT_FOUND).send({
          statusCode: HTTP_NOT_FOUND,
          error: "Not Found",
          message: `User ${request.params.id} not found`,
        });
      }
      return reply.status(HTTP_OK).send(user);
    },
  );
};

Why good: Response schemas enable fast-json-stringify (2-3x faster), full type inference on request objects, HTTP constants prevent magic numbers

Complete CRUD routes with pagination: [examples/core.md](examples/core.md)

Pattern 4: Plugin Encapsulation

Default plugins are encapsulated - decorators stay within scope. Use fastify-plugin (fp) to break encapsulation for shared infrastructure.

// ENCAPSULATED - decorators only available within this plugin
export const authRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.decorate("authConfig", { tokenExpiry: 3600 });
  // authConfig only accessible in this plugin
};

// SHARED - decorators exposed to parent scope
import fp from "fastify-plugin";

declare module "fastify" {
  interface FastifyInstance {
    config: AppConfig;
  }
}

const configPlugin: FastifyPluginAsync = async (fastify) => {
  fastify.decorate("config", { apiVersion: "v1" });
};

export const appConfig = fp(configPlugin, {
  name: "app-config",
  dependencies: [],
});

Why good: Domain plugins stay isolated, shared utilities use fp() to expose decorators, TypeScript augmentation provides type safety

Full plugin examples with dependencies, registration order: [examples/plugins.md](examples/plugins.md)

Pattern 5: Lifecycle Hooks

Use hooks for cross-cutting concerns at specific lifecycle points.

Hook execution order:

1. onRequest - Before parsing (request ID, timing)
2. preParsing - Transform request stream
3. preValidation - Before schema validation
4. preHandler - After validation (auth, authorization)
5. preSerialization - Transform response object
6. onSend - Final payload modification
7. onResponse - After response sent (metrics,