Fastify Complete Guide: High-Performance Node.js Web Framework

1. What Is Fastify?

Fastify is an open-source, high-performance web framework for Node.js created by Matteo Collina and Tomas Della Vedova in 2016. It is built on a radix-tree router (find-my-way) and leverages fast-json-stringify for response serialization that outperforms native JSON.stringify. Unlike Express, Fastify embraces a schema-first approach: define JSON Schemas for routes and get both validation (via Ajv) and fast serialization automatically. The plugin architecture ensures clean separation of concerns with encapsulated contexts.

2. Installation and Project Setup

Getting started with Fastify is straightforward. You can create a new project manually or use the Fastify CLI to scaffold a complete application with sensible defaults.

Manual Setup

# Create project directory
mkdir my-fastify-app && cd my-fastify-app
npm init -y

# Install Fastify
npm install fastify

# For TypeScript projects
npm install typescript @types/node tsx -D
npx tsc --init

Using Fastify CLI

# Generate a new Fastify project
npm install -g fastify-cli
fastify generate my-app --lang=ts
cd my-app && npm install && npm run dev

# Structure: src/app.ts, src/plugins/, src/routes/, test/

Minimal Server

import Fastify from 'fastify'

const fastify = Fastify({
  logger: true  // Enable Pino logging
})

fastify.get('/', async (request, reply) => {
  return { hello: 'world' }
})

const start = async () => {
  try {
    await fastify.listen({ port: 3000, host: '0.0.0.0' })
  } catch (err) {
    fastify.log.error(err)
    process.exit(1)
  }
}

start()

3. Routing (GET, POST, PUT, DELETE)

Fastify uses a highly optimized radix-tree router called find-my-way. Unlike Express regex-based routing, this provides O(1)-like lookup performance regardless of how many routes you register.

Basic CRUD Routes

import Fastify from 'fastify'
const app = Fastify({ logger: true })

// GET — List all users
app.get('/api/users', async (request, reply) => {
  const users = await db.findAllUsers()
  return users
})

// GET — Single user by ID
app.get('/api/users/:id', async (request, reply) => {
  const { id } = request.params as { id: string }
  const user = await db.findUser(id)
  if (!user) {
    reply.code(404)
    return { error: 'User not found' }
  }
  return user
})

// POST — Create user
app.post('/api/users', async (request, reply) => {
  const body = request.body as { name: string; email: string }
  const user = await db.createUser(body)
  reply.code(201)
  return user
})

// PUT — Update user
app.put('/api/users/:id', async (request, reply) => {
  const { id } = request.params as { id: string }
  const body = request.body as { name?: string; email?: string }
  const user = await db.updateUser(id, body)
  return user
})

// DELETE — Remove user
app.delete('/api/users/:id', async (request, reply) => {
  const { id } = request.params as { id: string }
  await db.deleteUser(id)
  reply.code(204)
  return
})

Route Options Object

app.route({
  method: 'GET',
  url: '/api/items/:id',
  schema: {
    params: {
      type: 'object',
      properties: { id: { type: 'string', pattern: '^[0-9a-f]{24}$' } },
      required: ['id']
    },
    response: {
      200: {
        type: 'object',
        properties: { id: { type: 'string' }, name: { type: 'string' }, price: { type: 'number' } }
      }
    }
  },
  handler: async (request) => {
    const { id } = request.params as { id: string }
    return db.findItem(id)
  }
})

4. Request/Reply Lifecycle

Understanding the Fastify lifecycle is essential for building robust applications. Every incoming request flows through a well-defined sequence of stages. This gives you precise control over when to authenticate, validate, transform, or log data.

// Fastify Request Lifecycle (in order):
//
// Incoming Request
//   └─> onRequest hooks
//       └─> preParsing hooks
//           └─> Body Parsing
//               └─> preValidation hooks
//                   └─> Schema Validation
//                       └─> preHandler hooks
//                           └─> Route Handler
//                               └─> preSerialization hooks
//                                   └─> Response Serialization
//                                       └─> onSend hooks
//                                           └─> Response Sent
//                                               └─> onResponse hooks

The request object provides access to headers, query parameters, body, params, IP address, and the underlying raw Node.js request. The reply object provides methods for setting status codes, headers, and sending responses. Fastify automatically serializes objects as JSON using fast-json-stringify when a response schema is provided.

5. Schema Validation with JSON Schema

One of Fastify's killer features is built-in schema validation. Define JSON Schemas for body, querystring, params, and headers. Fastify compiles these schemas at startup using Ajv (Another JSON Validator), so validation at runtime is extremely fast. Invalid requests automatically receive a 400 response.

const createUserSchema = {
  body: {
    type: 'object',
    required: ['name', 'email', 'password'],
    properties: {
      name: { type: 'string', minLength: 2, maxLength: 100 },
      email: { type: 'string', format: 'email' },
      password: { type: 'string', minLength: 8 },
      age: { type: 'integer', minimum: 0, maximum: 150 }
    },
    additionalProperties: false
  },
  response: {
    201: {
      type: 'object',
      properties: {
        id: { type: 'string' },
        name: { type: 'string' },
        email: { type: 'string' }
      }
    },
    400: {
      type: 'object',
      properties: {
        statusCode: { type: 'integer' },
        error: { type: 'string' },
        message: { type: 'string' }
      }
    }
  }
}

app.post('/api/users', { schema: createUserSchema }, async (request, reply) => {
  // request.body is already validated here
  const { name, email, password } = request.body as any
  const user = await createUser({ name, email, password })
  reply.code(201)
  return user
})

// Querystring validation
app.get('/api/users', {
  schema: {
    querystring: {
      type: 'object',
      properties: {
        page: { type: 'integer', minimum: 1, default: 1 },
        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
        search: { type: 'string' }
      }
    }
  }
}, async (request) => {
  const { page, limit, search } = request.query as any
  return db.findUsers({ page, limit, search })
})

6. Plugins and Decorators

Plugins are the backbone of Fastify application architecture. Everything in Fastify is a plugin: routes, hooks, decorators, and even other plugins. This design promotes modularity and enables clean code organization. Fastify uses avvio for asynchronous plugin loading with proper dependency resolution.

Creating Plugins

import fp from 'fastify-plugin'
import { FastifyInstance } from 'fastify'

// Encapsulated plugin (default) — decorators stay inside
async function userRoutes(fastify: FastifyInstance) {
  fastify.get('/users', async () => {
    return fastify.db.findAll('users')
  })

  fastify.post('/users', async (req) => {
    return fastify.db.create('users', req.body)
  })
}

// Shared plugin (breaks encapsulation) — decorators visible globally
const dbPlugin = fp(async function (fastify: FastifyInstance, opts) {
  const connection = await createDbConnection(opts.uri)
  fastify.decorate('db', connection)

  fastify.addHook('onClose', async () => {
    await connection.close()
  })
}, { name: 'db-plugin' })

// Register plugins
app.register(dbPlugin, { uri: 'postgres://localhost/mydb' })
app.register(userRoutes, { prefix: '/api' })

Decorators

// Decorate the Fastify instance
fastify.decorate('config', {
  jwtSecret: process.env.JWT_SECRET,
  dbUrl: process.env.DATABASE_URL
})

// Decorate the request object
fastify.decorateRequest('user', null)

// Decorate the reply object
fastify.decorateReply('sendSuccess', function (data: unknown) {
  return this.code(200).send({ success: true, data })
})

// Use decorators in routes
fastify.get('/me', async (request, reply) => {
  return reply.sendSuccess(request.user)
})

7. Hooks (onRequest, preHandler, onSend)

Hooks let you intercept the request/reply lifecycle at specific points. They are essential for cross-cutting concerns like authentication, logging, rate limiting, and response transformation. Hooks follow encapsulation rules just like plugins.

// onRequest — Runs first, before body parsing
// Great for authentication, rate limiting
fastify.addHook('onRequest', async (request, reply) => {
  request.startTime = Date.now()
  fastify.log.info('Request started: ' + request.method + ' ' + request.url)
})

// preHandler — After validation, before route handler
// Great for authorization, data enrichment
fastify.addHook('preHandler', async (request, reply) => {
  if (request.routeOptions.config.requireAuth) {
    const token = request.headers.authorization
    if (!token) {
      reply.code(401).send({ error: 'Unauthorized' })
      return
    }
    request.user = await verifyToken(token)
  }
})

// preSerialization — Transform payload before serialization
fastify.addHook('preSerialization', async (request, reply, payload) => {
  return {
    data: payload,
    timestamp: new Date().toISOString()
  }
})

// onSend — Modify the serialized response before sending
fastify.addHook('onSend', async (request, reply, payload) => {
  reply.header('X-Response-Time',
    String(Date.now() - (request as any).startTime) + 'ms'
  )
  return payload
})

// onResponse — After response is sent (logging, metrics)
fastify.addHook('onResponse', async (request, reply) => {
  fastify.log.info({
    method: request.method,
    url: request.url,
    statusCode: reply.statusCode,
    responseTime: reply.elapsedTime
  }, 'Request completed')
})

8. Serialization

Fastify uses fast-json-stringify to serialize response objects. When you define a response schema, Fastify compiles a specialized serialization function at startup. This is significantly faster than JSON.stringify because it knows the exact shape of the data. It also acts as a security layer, stripping any properties not defined in the schema.

app.get('/api/users/:id', {
  schema: {
    response: {
      200: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          name: { type: 'string' },
          email: { type: 'string' },
          // password field intentionally omitted —
          // fast-json-stringify will strip it automatically
        }
      }
    }
  }
}, async (request) => {
  const { id } = request.params as { id: string }
  // Even if the DB returns { id, name, email, password, ssn },
  // the response will only contain { id, name, email }
  return db.findUser(id)
})

// Custom serializer for specific content types
app.get('/api/report', {
  schema: {
    response: { 200: { type: 'string' } }
  }
}, async (request, reply) => {
  reply.type('text/csv')
  reply.serializer((data: any) => {
    return data.map((row: any) => Object.values(row).join(',')).join('\n')
  })
  return await db.getReport()
})

9. Logging with Pino

Fastify ships with Pino as its default logger, one of the fastest JSON loggers for Node.js. Pino adds minimal overhead (only ~5% compared to noop) and produces structured JSON logs that are ideal for production log aggregation systems like ELK, Datadog, or Grafana Loki.

import Fastify from 'fastify'

// Basic logger configuration
const app = Fastify({
  logger: {
    level: process.env.LOG_LEVEL || 'info',
    // Pretty-print in development
    transport: process.env.NODE_ENV !== 'production'
      ? { target: 'pino-pretty', options: { colorize: true } }
      : undefined,
    // Redact sensitive fields
    redact: ['req.headers.authorization', 'req.headers.cookie'],
    serializers: {
      req(request) {
        return {
          method: request.method,
          url: request.url,
          hostname: request.hostname,
        }
      }
    }
  }
})

// Use the logger in routes
app.get('/api/users', async (request) => {
  request.log.info('Fetching users list')
  const users = await db.findUsers()
  request.log.info({ count: users.length }, 'Users fetched')
  return users
})

// Child loggers with context
app.addHook('onRequest', async (request) => {
  request.log = request.log.child({ requestId: request.id })
})

10. Error Handling

Fastify provides multiple layers of error handling: schema validation errors (automatic 400), custom error handlers, and the @fastify/sensible plugin for HTTP-aware error utilities.

import Fastify from 'fastify'
import sensible from '@fastify/sensible'

const app = Fastify({ logger: true })
app.register(sensible)

// Custom error handler
app.setErrorHandler((error, request, reply) => {
  request.log.error({ err: error }, 'Request error')
  if (error.validation) {
    return reply.code(400).send({
      statusCode: 400, error: 'Validation Error',
      message: error.message, details: error.validation
    })
  }
  const code = error.statusCode || 500
  reply.code(code).send({
    statusCode: code, error: error.name || 'Internal Server Error',
    message: code === 500 ? 'An unexpected error occurred' : error.message
  })
})

// Custom 404 handler
app.setNotFoundHandler((request, reply) => {
  reply.code(404).send({
    statusCode: 404, error: 'Not Found',
    message: 'Route ' + request.method + ':' + request.url + ' not found'
  })
})

// Using @fastify/sensible HTTP errors in routes
app.get('/api/users/:id', async (request) => {
  const { id } = request.params as { id: string }
  const user = await db.findUser(id)
  if (!user) throw app.httpErrors.notFound('User not found')
  return user
})

11. TypeScript Support

Fastify has first-class TypeScript support. You can type request bodies, query strings, params, headers, and responses using generics or Type Providers for automatic inference from JSON schemas.

Typed Routes with Generics

import Fastify, { FastifyRequest, FastifyReply } from 'fastify'

interface CreateUserBody {
  name: string
  email: string
  password: string
}

interface UserParams {
  id: string
}

interface ListQuery {
  page?: number
  limit?: number
}

const app = Fastify()

app.post<{ Body: CreateUserBody }>(
  '/api/users',
  async (request) => {
    // request.body is typed as CreateUserBody
    const { name, email, password } = request.body
    return { id: '1', name, email }
  }
)

app.get<{ Params: UserParams; Querystring: ListQuery }>(
  '/api/users/:id',
  async (request) => {
    const { id } = request.params    // typed as UserParams
    const { page } = request.query   // typed as ListQuery
    return db.findUser(id)
  }
)

Type Providers (TypeBox)

import Fastify from 'fastify'
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
import { Type, Static } from '@sinclair/typebox'

const app = Fastify().withTypeProvider<TypeBoxTypeProvider>()

const UserSchema = Type.Object({
  name: Type.String({ minLength: 2 }),
  email: Type.String({ format: 'email' }),
  age: Type.Optional(Type.Integer({ minimum: 0 }))
})

type User = Static<typeof UserSchema>

app.post('/api/users', {
  schema: { body: UserSchema }
}, async (request) => {
  // request.body is automatically typed as User
  const { name, email, age } = request.body
  return { id: '1', name, email, age }
})

12. Authentication (JWT and OAuth)

Fastify has an excellent ecosystem for authentication. The @fastify/jwt plugin provides JWT signing and verification, while @fastify/oauth2 handles OAuth2 flows with providers like Google, GitHub, and Facebook.

JWT Authentication

import Fastify from 'fastify'
import fastifyJwt from '@fastify/jwt'

const app = Fastify({ logger: true })

app.register(fastifyJwt, {
  secret: process.env.JWT_SECRET || 'supersecret',
  sign: { expiresIn: '1h' }
})

// Auth decorator
app.decorate('authenticate', async (request: any, reply: any) => {
  try {
    await request.jwtVerify()
  } catch (err) {
    reply.code(401).send({ error: 'Unauthorized' })
  }
})

// Login route — issue token
app.post('/api/login', async (request) => {
  const { email, password } = request.body as any
  const user = await verifyCredentials(email, password)
  const token = app.jwt.sign({
    sub: user.id,
    email: user.email,
    role: user.role
  })
  return { token }
})

// Protected route
app.get('/api/profile', {
  preHandler: [app.authenticate]
}, async (request) => {
  // request.user contains decoded JWT payload
  return db.findUser(request.user.sub)
})

OAuth2 with Google

import oauthPlugin from '@fastify/oauth2'

app.register(oauthPlugin, {
  name: 'googleOAuth2',
  credentials: {
    client: { id: process.env.GOOGLE_CLIENT_ID, secret: process.env.GOOGLE_CLIENT_SECRET },
    auth: oauthPlugin.GOOGLE_CONFIGURATION
  },
  startRedirectPath: '/auth/google',
  callbackUri: 'https://myapp.com/auth/google/callback',
  scope: ['profile', 'email']
})

app.get('/auth/google/callback', async (request, reply) => {
  const { token } = await app.googleOAuth2
    .getAccessTokenFromAuthorizationCodeFlow(request)
  const profile = await fetchGoogleProfile(token.access_token)
  const jwt = app.jwt.sign({ sub: profile.id, email: profile.email })
  reply.redirect('/dashboard?token=' + jwt)
})

13. Database Integration (Prisma and TypeORM)

Fastify integrates cleanly with any database library through its plugin system. Here are examples with two popular ORMs: Prisma and TypeORM.

Prisma Integration

// plugins/prisma.ts
import fp from 'fastify-plugin'
import { PrismaClient } from '@prisma/client'

export default fp(async (fastify) => {
  const prisma = new PrismaClient({
    log: ['query', 'warn', 'error']
  })

  await prisma.$connect()
  fastify.decorate('prisma', prisma)

  fastify.addHook('onClose', async () => {
    await prisma.$disconnect()
  })
})

// routes/users.ts
export default async function userRoutes(fastify: any) {
  fastify.get('/users', async (request: any) => {
    const { page = 1, limit = 20 } = request.query
    return fastify.prisma.user.findMany({
      skip: (page - 1) * limit,
      take: limit,
      select: { id: true, name: true, email: true, createdAt: true }
    })
  })

  fastify.post('/users', async (request: any, reply: any) => {
    const user = await fastify.prisma.user.create({ data: request.body })
    reply.code(201)
    return user
  })
}

TypeORM Integration

// plugins/typeorm.ts
import fp from 'fastify-plugin'
import { DataSource } from 'typeorm'
import { User } from '../entities/User'

export default fp(async (fastify) => {
  const ds = new DataSource({
    type: 'postgres', host: process.env.DB_HOST, port: 5432,
    username: process.env.DB_USER, password: process.env.DB_PASS,
    database: process.env.DB_NAME, entities: [User],
    synchronize: process.env.NODE_ENV !== 'production'
  })
  await ds.initialize()
  fastify.decorate('orm', ds)
  fastify.addHook('onClose', async () => { await ds.destroy() })
})

// Use in routes
app.get('/users', async () => {
  return app.orm.getRepository(User).find({ take: 20, order: { createdAt: 'DESC' } })
})

14. Testing with inject()

Fastify provides a built-in inject() method that simulates HTTP requests without starting a real server. This makes tests fast, reliable, and free of port conflicts. It works seamlessly with any test runner: Vitest, Jest, tap, or Node.js native test runner.

// app.ts — Export a build function
import Fastify from 'fastify'

export function buildApp() {
  const app = Fastify({ logger: false })

  app.get('/api/health', async () => ({ status: 'ok' }))

  app.post('/api/users', {
    schema: {
      body: {
        type: 'object',
        required: ['name', 'email'],
        properties: {
          name: { type: 'string' },
          email: { type: 'string', format: 'email' }
        }
      }
    }
  }, async (request, reply) => {
    reply.code(201)
    return { id: '1', ...request.body as object }
  })

  return app
}

// app.test.ts — Tests using inject()
import { describe, it, expect, beforeEach } from 'vitest'
import { buildApp } from './app'

describe('User API', () => {
  let app: ReturnType<typeof buildApp>

  beforeEach(async () => {
    app = buildApp()
    await app.ready()
  })

  it('GET /api/health returns 200', async () => {
    const res = await app.inject({
      method: 'GET',
      url: '/api/health'
    })
    expect(res.statusCode).toBe(200)
    expect(res.json()).toEqual({ status: 'ok' })
  })

  it('POST /api/users creates user', async () => {
    const res = await app.inject({
      method: 'POST',
      url: '/api/users',
      payload: { name: 'Alice', email: 'alice@example.com' }
    })
    expect(res.statusCode).toBe(201)
    expect(res.json().name).toBe('Alice')
  })

  it('POST /api/users rejects invalid email', async () => {
    const res = await app.inject({
      method: 'POST',
      url: '/api/users',
      payload: { name: 'Bob', email: 'not-an-email' }
    })
    expect(res.statusCode).toBe(400)
  })
})

15. Production Deployment

Deploying Fastify to production requires attention to host binding, process management, graceful shutdown, and reverse proxy configuration. Here is a production-ready setup.

Production Server Configuration

import Fastify from 'fastify'
import closeWithGrace from 'close-with-grace'

const app = Fastify({
  logger: { level: 'info', redact: ['req.headers.authorization'] },
  trustProxy: true,       // Behind Nginx/Caddy
  requestTimeout: 30000,  // 30s timeout
  bodyLimit: 1048576      // 1MB body limit
})

app.register(import('@fastify/cors'), { origin: ['https://myapp.com'], credentials: true })
app.register(import('@fastify/helmet'))
app.register(import('@fastify/rate-limit'), { max: 100, timeWindow: '1 minute' })

// Graceful shutdown
closeWithGrace({ delay: 5000 }, async ({ err }) => {
  if (err) app.log.error(err, 'Closing due to error')
  await app.close()
})

app.listen({ port: 3000, host: '0.0.0.0' }) // Bind to 0.0.0.0

PM2 Ecosystem File

// ecosystem.config.cjs
module.exports = {
  apps: [{
    name: 'fastify-app',
    script: './dist/server.js',
    instances: 'max',          // Use all CPU cores
    exec_mode: 'cluster',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    max_memory_restart: '500M',
    error_file: './logs/error.log',
    out_file: './logs/output.log'
  }]
}

Nginx Reverse Proxy

upstream fastify_backend {
  server 127.0.0.1:3000;
  keepalive 64;
}
server {
  listen 443 ssl http2;
  server_name api.myapp.com;
  ssl_certificate     /etc/letsencrypt/live/api.myapp.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/api.myapp.com/privkey.pem;
  location / {
    proxy_pass http://fastify_backend;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

16. Performance: Fastify vs Express

Fastify consistently outperforms Express in all benchmark categories. The performance gains come from architectural decisions: schema-based serialization, radix-tree routing, and minimal per-request overhead.

The schema compilation step happens once at startup, making every subsequent request faster. For APIs handling thousands of concurrent requests, Fastify can reduce infrastructure costs through higher throughput per instance.

17. Essential Fastify Plugins

The Fastify ecosystem includes official plugins for common needs. Key plugins include: @fastify/cors (CORS headers), @fastify/helmet (security headers), @fastify/rate-limit (rate limiting with Redis), @fastify/jwt (JWT auth), @fastify/sensible (HTTP error utilities), @fastify/swagger (auto OpenAPI docs), @fastify/multipart (file uploads), @fastify/cookie (cookie handling), @fastify/websocket (WebSocket support), and @fastify/static (static file serving).

18. Frequently Asked Questions