Skip to content
Ideony

ADR 0003: NestJS 11 + Fastify over Express

ADR 0003: NestJS 11 + Fastify over Express

Section titled “ADR 0003: NestJS 11 + Fastify over Express”
  • Status: Accepted
  • Date: 2026-04-14
  • Deciders: Ideony team

Context

Section titled “Context”

The API backend needs a structured Node.js framework with TypeScript decorators, dependency injection, and WebSocket support. Two viable options were NestJS (with either Fastify or Express adapter) and a lightweight Express/Hono setup.

Decision

Section titled “Decision”

Use NestJS 11 with the Fastify adapter, compiled via SWC for faster TypeScript builds. Parameter decorators are enabled (unsafeParameterDecoratorsEnabled). Biome handles linting/formatting (not ESLint/Prettier).

Consequences

Section titled “Consequences”
  • NestJS DI system enables modular architecture that is extractable to microservices later.
  • Fastify adapter delivers ~2× the throughput of Express under load.
  • SWC compilation is significantly faster than tsc for watch mode.
  • Decorators and module system map directly to domain concepts (BookingModule, SosModule, etc.).
  • Fastify requires req.rawBody preservation for Stripe/Clerk webhook signature verification — must be explicitly configured.
  • NestJS DI runtime class references mean useImportType must stay OFF in Biome config.
  • OpenAPI spec generation requires building to dist/ first; tsx cannot resolve NestJS DI at runtime.

Alternatives considered

Section titled “Alternatives considered”
  • Express + ts-rest — rejected: no built-in DI, more boilerplate for module boundaries.
  • Hono — rejected: too minimal; lacks built-in DI, guards, interceptors, and decorators needed for the domain.