A production-ready Fastify 5 boilerplate built on Clean Architecture, CQRS, DDD, and functional programming. Designed as a starting point for real-world applications, the architecture is framework-agnostic at its core — the patterns and boundaries translate to any language or framework.

• Features
• Prerequisites
• Getting Started
• Available Scripts
• Running with Docker
• API Endpoints
• Architecture
  • Principles
  • Modules
  • Module Components
• Folder Structure
• OpenTelemetry
• Testing
• Client Types Package
• CI/CD Pipeline
• AI-Assisted Development
• Why Biome over ESLint + Prettier?
• Useful Resources
• Contributing
• License

# 1. Scaffold from the template
npx degit marcoturi/fastify-boilerplate my-app
cd my-app

# 2. Install dependencies
pnpm install

# 3. Create your .env file
pnpm create:env          # copies .env.example → .env

# 4. Start PostgreSQL (pick one)
docker compose up postgres -d   # via Docker Compose
# — or use a local Postgres and adjust .env values —

# 5. Run database migrations
pnpm db:migrate

# 6. Start the dev server (with watch mode and pretty logs)
pnpm start

The server starts at http://localhost:3000 by default. See API Endpoints for what's available.

pnpm create:env       # create .env from .env.example (if not done already)
docker compose up     # builds the app image and starts all services

docker build -t fastify-boilerplate .
docker run -p 3000:3000 --env-file .env -e HOST=0.0.0.0 fastify-boilerplate

• Multi-stage build — dependencies installed in an isolated stage for optimal layer caching
• Node Alpine — small footprint, native TypeScript execution (no build step)
• Non-root user — runs as an unprivileged fastify user (UID 1001)
• dumb-init — proper PID 1 signal forwarding for graceful shutdown
• HEALTHCHECK — built-in Docker health check against /health every 30 seconds

^{Diagram adapted from Domain-Driven Hexagon}

Project-level:

• Adaptable complexity — the structure scales up or down by adding or removing layers to match the application's actual needs.
• Future-proofing — framework code and business logic are separated. Dependencies are well-established and minimal.
• Functional programming first — composition and factory functions over classes and inheritance.
• Microservices-ready — vertical slices, path aliases, and CQRS make it straightforward to extract a module into its own service later.

Code-level:

• Framework-agnostic core — business logic has no Fastify dependency. Fastify concerns stay in routes.
• Protocol-agnostic handlers — command/query handlers serve REST, GraphQL, gRPC, or CLI equally.
• Database-agnostic domain — SQL stays in repository files. Handlers interact with data through repository ports (interfaces).
• Inward dependency flow — outer layers depend on inner layers, never the reverse: Route → Handler → Domain → Repository.

Based on:

• Domain-Driven Design (DDD)
• Hexagonal (Ports and Adapters) Architecture
• Clean Architecture
• Onion Architecture
• SOLID Principles
• Vertical Slice Architecture
• Common Closure Principle (CCP)

Each module maps to a domain concept and lives in its own folder under src/modules/. Modules follow the vertical slice architecture — everything a feature needs is co-located.

Key rules:

• No direct imports between modules. Cross-module communication uses the CQRS buses (commands/queries for request-response, events for fire-and-forget).
• Extractable — any module can be pulled into a separate microservice. The CQRS handler boundary becomes the network boundary.
• If two modules are too "chatty", they probably belong together — merge them.

Each layer has a single responsibility:

Route — handles the HTTP/GraphQL/gRPC request. Validates input, formats the response. No business logic.

All REST routes are prefixed with /api (configured in src/server/index.ts).

Example: find-users.route.ts

Command/Query Handler — orchestrates the use case. Receives a command or query, calls domain services and repositories through ports, returns a result. One handler per use case (e.g. CreateUser, FindUsers).

Benefits of the CQRS bus pattern:

• Middlewares — cross-cutting concerns (auth, caching, tracing, rate limiting) plug in between route and handler. Middleware targeting is pattern-based (e.g. users/* for all user commands, users/create for a specific one). See middlewares.ts.
• Decoupling — modules communicate through the bus instead of direct imports, making future extraction to microservices trivial.

Example: find-users.handler.ts

Domain Service — pure business logic. Computes properties, enforces invariants, composes entities. No infrastructure dependencies.

Example: user.domain.ts

Repository — data access. Converts between domain models and database rows. All SQL lives here. Implements a port (interface) defined alongside it.

Example: user.repository.ts

Guideline: use as many or as few layers as needed. Not every feature requires a domain service — simpler CRUD operations can go straight from handler to repository.

.
├── db/
│   ├── migrations/                → SQL migration files (DBMate)
│   └── seeds/                     → SQL seed files (DBMate)
├── tests/
│   ├── <feature>/
│   │   ├── <scenario>.feature     → Gherkin E2E scenarios
│   │   └── <scenario>.k6.ts      → k6 load test scripts
│   ├── shared/                    → Shared step definitions
│   └── support/                   → Test server, hooks, custom world
├── client/                        → Generated REST + GraphQL client types (npm package)
├── scripts/                       → Type generation scripts
└── src/
    ├── instrumentation.ts         → OpenTelemetry setup (loaded via --import)
    ├── config/                    → Environment validation (env-schema + TypeBox)
    ├── modules/
    │   └── <feature>/
    │   │   ├── commands/
    │   │   │   └── <command>/
    │   │   │       ├── command.handler.ts         → Command handler
    │   │   │       ├── command.route.ts           → REST route
    │   │   │       ├── command.resolver.ts        → GraphQL resolver
    │   │   │       ├── command.graphql-schema.ts  → GraphQL type definitions
    │   │   │       └── command.schema.ts          → TypeBox request/response schemas
    │   │   ├── queries/
    │   │   │   └── <query>/
    │   │   │       ├── query.handler.ts           → Query handler
    │   │   │       ├── query.route.ts             → REST route
    │   │   │       ├── query.resolver.ts          → GraphQL resolver
    │   │   │       ├── query.graphql-schema.ts    → GraphQL type definitions
    │   │   │       └── query.schema.ts            → TypeBox request/response schemas
    │   │   ├── database/
    │   │   │   ├── feature.repository.port.ts     → Repository interface (port)
    │   │   │   └── feature.repository.ts          → Repository implementation (adapter)
    │   │   ├── domain/
    │   │   │   ├── feature.domain.ts              → Domain service
    │   │   │   ├── feature.errors.ts              → Domain-specific errors
    │   │   │   └── feature.types.ts               → Domain types
    │   │   ├── dtos/
    │   │   │   ├── feature.graphql-schema.ts      → Shared GraphQL schema
    │   │   │   └── feature.response.dto.ts        → Shared response DTO
    │   │   ├── index.ts                           → Action creators, DI declarations
    │   │   └── feature.mapper.ts                  → Entity ↔ DB model ↔ DTO mapper
    ├── server/
    │   ├── index.ts               → Fastify instance setup
    │   └── plugins/               → Fastify plugins (swagger, CORS, error handler, CQRS, etc.)
    └── shared/
        ├── cqrs/                  → Command/Query/Event bus, middlewares
        ├── db/                    → Postgres connection, transaction helpers, repository base
        ├── exceptions/            → Base exception classes
        └── utils/                 → Cross-cutting utilities

The project ships with a vendor-agnostic OpenTelemetry setup in src/instrumentation.ts. It uses the standard OTLP protocol, so it works with any backend (Grafana, Datadog, Honeycomb, Jaeger, etc.) without code changes.

How it works:

• HTTP + Fastify — the SDK registers the ESM loader hook and initialises with instrumentation-http and @fastify/otel. Every request gets a trace span with route, method, status code, and lifecycle hooks.
• CQRS — a tracing middleware in src/shared/cqrs/otel-middleware.ts wraps every command, query, and event in a span. Spans include the action type, bus kind, and correlation ID.
• Disabled by default (OTEL_SDK_DISABLED=true). When disabled, @opentelemetry/api returns noop implementations — zero overhead.

To enable, set the standard OTel environment variables in your .env:

OTEL_SDK_DISABLED=false
OTEL_SERVICE_NAME=fastify-boilerplate
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # your OTLP collector

All configuration uses standard OTel environment variables — no vendor lock-in.

Run with node:test. Test files live next to their source files as *.spec.ts.

pnpm test:unit           # run tests
pnpm test:coverage       # run with c8 coverage

Written in Gherkin and executed with Cucumber.js. Scenarios live in tests/<feature>/<scenario>.feature, step definitions in tests/<feature>/<feature>.steps.ts.

# Requires a running Postgres with migrations applied
pnpm test:e2e

The E2E test server is created via buildApp() (in tests/support/server.ts) — it boots a full Fastify instance without binding to a port, so tests run fast and don't conflict with a running dev server.

k6 scripts live alongside their feature's E2E tests.

Example: create-user.k6.ts

The release pipeline automatically generates REST (OpenAPI) and GraphQL client types and publishes them as the @marcoturi/fastify-boilerplate npm package. The version is kept in sync with the backend via semantic-release.

pnpm add -D @marcoturi/fastify-boilerplate

// REST types (generated by openapi-typescript)
import type { paths, components } from '@marcoturi/fastify-boilerplate/rest';

// GraphQL types (generated by graphql-codegen)
import type { User, Query, Mutation } from '@marcoturi/fastify-boilerplate/graphql';

To regenerate the types against a local server (requires running Postgres with migrations applied):

pnpm generate:types

This starts the server, fetches the OpenAPI and GraphQL schemas, writes the type files to client/, and stops the server.

The project uses GitHub Actions with two workflows:

release.yml — runs on every push to main:

1. Install dependencies (pnpm install --frozen-lockfile)
2. Code quality checks (pnpm check)
3. Unit tests (pnpm test)
4. E2E tests (pnpm test:e2e) against a Postgres service container
5. Generate client types (pnpm generate:types)
6. Publish release via semantic-release (changelog, GitHub release, npm client package)

codeql-analysis.yml — runs on pushes and PRs to main:

• GitHub CodeQL security analysis for JavaScript/TypeScript

This project ships with an AGENTS.md file — a comprehensive guide for AI coding assistants. It documents the architecture, CQRS patterns, coding conventions, and common pitfalls so that tools like Cursor, Claude Code, and GitHub Copilot can generate code that follows the project's established patterns.

AI assistants automatically pick up AGENTS.md and apply the conventions without manual prompting.

This project uses Biome as a single tool for linting, formatting, and import sorting:

• One tool, zero plugins — no @typescript-eslint/parser, eslint-config-prettier, eslint-plugin-import, or other ecosystem packages to keep in sync.
• Fast — written in Rust, orders of magnitude faster than ESLint + Prettier. Noticeable in CI and pre-commit hooks.
• Stable — no more breakage from mismatched plugin versions or peer dependency conflicts across the ESLint ecosystem.
• Mature — covers the vast majority of rules that ESLint + typescript-eslint provide, with a growing community and clear roadmap.

• Domain-Driven Hexagon — the primary inspiration for this project's architecture (adapted toward functional programming)
• react-redux boilerplate — companion frontend boilerplate by the same author

Contributions are welcome! This project uses Conventional Commits enforced by Commitlint and Husky.

1. Fork and clone the repo
2. Create a branch: git checkout -b your-feature
3. Make your changes
4. Run pnpm check to validate lint, format, and types
5. Run pnpm test (and pnpm test:e2e if your change touches API behavior)
6. Commit using Conventional Commits format (e.g. feat: add user roles)
7. Open a Pull Request

MIT