fastify-typescript

Fastify TypeScript Patterns

Type Providers (Preferred Approach)

NEVER duplicate TypeScript interfaces AND JSON schemas for the same data shape. Use a Type Provider to infer types directly from schemas, eliminating the second source of truth entirely.

Type Providers statically infer TypeScript types from inline JSON Schemas at compile time. This means runtime validation is guaranteed to match compile-time types -- a non-negotiable contract that eliminates an entire class of bugs where validation and types drift apart.

When a route defines a schema, the Type Provider analyzes that schema and automatically types request.body, request.query, and request.params inside the handler. If you change a schema field, incorrect handler code is immediately flagged at compile time. You get safety without ceremony.

Available Providers

Choose one of these two providers for your project:

• @fastify/type-provider-typebox -- Uses TypeBox schemas. This is the recommended provider and offers the best developer experience. TypeBox schemas are composable, reusable TypeScript objects that produce both JSON Schema and static types from a single definition.
• @fastify/type-provider-json-schema-to-ts -- Uses raw JSON Schema objects with as const assertions. Choose this when you already have existing JSON Schema definitions or prefer writing schemas in plain JSON Schema format.

Usage Pattern with TypeBox

Apply the Type Provider to your Fastify instance using withTypeProvider<T>(), then define route schemas using TypeBox's Type builder. The handler parameters are fully typed automatically:

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

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

app.post('/user', {
  schema: {
    body: Type.Object({
      name: Type.String(),
      age: Type.Number()
    }),
    response: {
      200: Type.Object({
        id: Type.String(),
        name: Type.String(),
        age: Type.Number()
      })
    }
  }
}, (request, reply) => {
  // request.body is fully typed: { name: string; age: number }
  const { name, age } = request.body
  return reply.send({ id: 'generated-id', name, age })
})