Typing Express/Fastify Handlers

Type-safe HTTP handlers catch bad body, params, and query shapes at compile time - pair Express 5 generics and Fastify 5 schema inference with runtime validation at boundaries.

Recipe

// Express 5 - typed body via generic (after validation middleware)
import type { Request, Response } from 'express';
 
interface CreateUserBody { email: string; name: string }
 
export async function createUser(
  req: Request<unknown, unknown, CreateUserBody>,
  res: Response,
): Promise<void> {
  res.status(201).json({ id: '1', ...req.body });
}

// Fastify 5 - schema-driven types
import Fastify from 'fastify';
 
const app = Fastify();
 
app.post<{ Body: { email: string } }>('/users', async (req, reply) => {
  return reply.code(201).send({ id: '1', email: req.body.email });
});

When to reach for this:

• CRUD APIs with repeated param shapes (id, pagination)
• Auth middleware attaching userId to requests
• Shared handler utilities across routers
• Preventing req.body.foo typos before runtime

Working Example

// express-app.d.ts - augmentation
import 'express-serve-static-core';
 
declare module 'express-serve-static-core' {
  interface Request {
    userId?: string;
  }
}

// auth-middleware.ts
import type { Request, Response, NextFunction } from 'express';
 
export function requireAuth(req: Request, res: Response, next: NextFunction): void {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    res.status(401).json({ error: 'unauthorized' });
    return;
  }
  req.userId = 'user-123';
  next();
}

// fastify-route.ts
import Fastify from 'fastify';
import { z } from 'zod';
 
const app = Fastify();
 
const CreateUser = z.object({ email: z.string().email(), name: z.string().min(1) });
 
app.post('/users', {
  schema: {
    body: {
      type: 'object',
      required: ['email', 'name'],
      properties: { email: { type: 'string' }, name: { type: 'string' } },
    },
  },
}, async (req, reply) => {
  const body = CreateUser.parse(req.body);
  return reply.code(201).send({ id: '1', ...body });
});

What this demonstrates:

• Express augmentation adds userId with proper typing across handlers
• Middleware should call next() or end response - typed NextFunction for errors
• Fastify JSON Schema validates at runtime; Zod adds stricter rules (email format)
• Parse after schema validation for complex rules Express/Fastify schemas cannot express

Deep Dive

How It Works

• Express uses Request<P, ResBody, ReqBody, ReqQuery, Locals> generics - rarely all filled manually; augmentation for cross-cutting fields.
• Fastify infers types from schema when using as const or TypeBox - Zod bridge via fastify-type-provider-zod.
• Response typing - res.json<T>() is not enforced at runtime - still validate outbound DTOs for public APIs.
• Error middleware - Express (err, req, res, next); Fastify setErrorHandler with typed errors.

Handler Typing Patterns

TypeScript Notes

import type { FastifyRequest, FastifyReply } from 'fastify';
 
type AuthedRequest = FastifyRequest & { userId: string };
 
function getUserId(req: FastifyRequest): string {
  return (req as AuthedRequest).userId;
}

Prefer plugins/decorators (fastify.decorateRequest) over casts when possible.

Gotchas

• Trusting req.body without validation - types lie at runtime. Fix: Zod parse at boundary per Zod at Boundaries.
• Over-generic Request everywhere - any leaks via defaults. Fix: per-route handler types or shared AppRequest alias.
• Mismatch Express types version - @types/express must match Express 5. Fix: align versions in package.json.
• Fastify schema and Zod drift - two sources of truth. Fix: generate JSON Schema from Zod or use type provider.
• Async middleware typing - returning rejected Promise without next(err) in Express. Fix: wrap async middleware utilities.

Alternatives

FAQs

Related

• Zod at Boundaries - runtime validation
• Express Basics - Express 5 patterns
• Fastify Basics - Fastify 5 setup
• Sharing Types with Frontend - DTO packages

External Related Links

• Express.js - Official Express site and guides.
• Fastify - High-performance web framework docs.
• NestJS Documentation - Progressive Node.js framework docs.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js in Action, 2nd Edition - Classic practical Node.js.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.