GitHub - Proskynete/node-api-skeleton: This is a repository meant to serve as a starting point if you want to start a TypeScript express API project with some common features already set up and best practices.

Production-ready Node.js API skeleton built with Hexagonal Architecture, Fastify, TypeScript, DDD, and modern best practices. Perfect starting point for scalable, maintainable API projects.

Status

🎉 Architecture Status: PRODUCTION READY

Version 2.0 - Migration to Hexagonal Architecture + Fastify COMPLETED!

All 8 migration stages completed ✅

✅ Stage 0: SWC compiler, Fastify dependencies, path aliases
✅ Stage 1: Hexagonal folder structure, Zod validation, Fastify server
✅ Stage 2: Domain layer (entities, value objects, ports)
✅ Stage 3: Application layer (use cases, DTOs, mappers)
✅ Stage 4: Infrastructure layer (controllers, routes, repositories)
✅ Stage 5: Dependency Injection with Awilix
✅ Stage 6: Observability (Winston logging + Prometheus metrics)
✅ Stage 7: Testing (Vitest + k6 performance tests)
✅ Stage 8: Cleanup, documentation, Docker production setup

📋 Table of Contents

🚀 Using as Template

This skeleton is designed to be used as a starting point for your Node.js API projects. You have two options:

Option 1: Use as GitHub Template (Recommended)

Click the "Use this template" button at the top of this repository
Create your new repository with your project name
Clone your new repository
Follow the Setup Guide to customize for your project

Option 2: Clone and Explore First

Want to explore the skeleton before committing?

# Clone this repository
git clone https://github.com/Proskynete/node-api-skeleton.git
cd node-api-skeleton

# Install dependencies
npm install

# Start development server
npm run dev

Visit http://localhost:3000/api/v1/greetings to see it in action!

Once you're ready to use it as a template, follow the Setup Guide.

✨ Highlights

🏗️ Modern Architecture

Hexagonal Architecture (Ports & Adapters) for clean separation of concerns
Onion Architecture with dependency inversion
Screaming Architecture - folder structure reflects business capabilities
DDD (Domain-Driven Design) with entities, value objects, and aggregates
Vertical Slice organization by bounded contexts

⚡ Performance

Fastify - 2x faster than Express
SWC - Ultra-fast TypeScript compiler (20x faster than tsc)
Build time: ~56ms (was ~2-3s with tsc)
Production-ready with Docker multi-stage builds

🧪 Testing & Quality

Vitest - Lightning-fast unit & integration tests
k6 - Performance/load testing with thresholds
98%+ coverage - 244 comprehensive tests across all layers
Type-safe validation with Zod
ESLint + Prettier - Code quality enforcement

📊 Observability

Winston - Structured JSON logging
Prometheus - Metrics collection (requests, latency, errors)
Grafana - Metrics visualization
Health checks - Liveness & readiness probes
OpenAPI - Interactive API documentation

🐳 DevOps Ready

Docker multi-stage builds (minimal Alpine images)
Docker Compose stacks for dev & production
Non-root user for security
Health checks integrated
Prometheus + Grafana stack included

⚙️ Features

Core Stack

✅ Fastify - High-performance web framework
✅ TypeScript - Type-safe JavaScript
✅ SWC - Ultra-fast TypeScript compiler
✅ Zod - Runtime schema validation
✅ Awilix - Dependency injection

Testing

✅ Vitest - Fast unit & integration tests
✅ Supertest - HTTP endpoint testing
✅ k6 - Load & performance testing
✅ Pact - Contract testing framework
✅ Coverage reports with v8

Observability

✅ Winston - Structured logging
✅ Prometheus - Metrics collection
✅ prom-client - Prometheus client
✅ Health checks (liveness/readiness)
✅ Swagger/OpenAPI - API documentation

Security & Best Practices

✅ @fastify/helmet - Security headers
✅ @fastify/cors - CORS support
✅ @fastify/rate-limit - Rate limiting
✅ Environment validation with Zod
✅ Docker non-root user
✅ Immutable domain entities
✅ ADRs (Architecture Decision Records)

Development Tools

✅ ESLint - Code linting
✅ Prettier - Code formatting
✅ Husky - Git hooks
✅ lint-staged - Pre-commit checks
✅ Nodemon - Dev server auto-reload

🏗️ Architecture

Hexagonal Architecture

The application follows Hexagonal Architecture (Ports & Adapters):

┌─────────────────────────────────────────┐
│  Infrastructure (Adapters)              │  ← Fastify, DB, External APIs
├─────────────────────────────────────────┤
│  Application (Use Cases)                │  ← Business orchestration
├─────────────────────────────────────────┤
│  Domain (Business Logic)                │  ← Pure business rules
└─────────────────────────────────────────┘

Dependency Rule: Dependencies point inward only

Infrastructure → Application → Domain
Domain has zero framework dependencies

Vertical Slice by Contexts

Each bounded context is a complete vertical slice:

@contexts/greetings/
├── domain/            # Entities, Value Objects, Business Rules
├── application/       # Use Cases, DTOs, Mappers, Ports
└── infrastructure/    # Controllers, Routes, Repositories

Benefits:

High cohesion - related code lives together
Easy to navigate - no jumping between layers
Scalable - add new contexts without touching existing ones
Microservices-ready - easy to extract contexts

See ARCHITECTURE.md for complete documentation.

📁 Folder Structure

src/
├── @contexts/                 # Business Features (Bounded Contexts)
│   └── greetings/
│       ├── domain/            # Business Logic (framework-independent)
│       │   ├── entities/      # Greeting entity
│       │   ├── value-objects/ # Message value object
│       │   └── exceptions/    # Domain exceptions
│       ├── application/       # Use Cases & Orchestration
│       │   ├── v1/            # API version 1
│       │   │   ├── use-cases/ # GetGreetingUseCase
│       │   │   ├── dtos/      # Request/Response DTOs
│       │   │   ├── mappers/   # Domain ↔ DTO transformation
│       │   │   └── ports/     # Interfaces (inbound/outbound)
│       │   └── v2/            # API version 2 (enhanced)
│       └── infrastructure/    # Adapters (HTTP, DB, External)
│           ├── http/          # Controllers & Routes (v1, v2)
│           └── persistence/   # Repository implementations
│
├── @shared/                   # Cross-Cutting Concerns
│   ├── domain/                # Shared domain concepts
│   ├── infrastructure/
│   │   ├── config/            # Environment, DI container
│   │   ├── http/              # Fastify app, plugins
│   │   └── observability/     # Winston, Prometheus
│   ├── types/                 # Common types
│   ├── utils/                 # Pure utility functions
│   └── constants/             # HTTP status codes, etc.
│
├── @app/                      # Application Bootstrap
│   └── server/                # Fastify configuration
│
└── main.ts                    # Entry point

🚀 Quick Start

Note: These instructions are for exploring the skeleton. If you've already created a project from this template, see the Setup Guide instead.

Prerequisites

Node.js >= 20
npm >= 10
Docker (optional, for containerized setup)
k6 (optional, for performance tests)

Installation

# Clone repository
git clone https://github.com/Proskynete/node-api-skeleton.git
cd node-api-skeleton

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start development server
npm run dev

The API will be running at http://localhost:3000

Available Scripts

# Development
npm run dev              # Start dev server with hot reload (SWC)
npm run build            # Build production bundle (SWC)
npm start                # Run production server

# Testing
npm run test             # Run all tests (Vitest)
npm run test:watch       # Run tests in watch mode
npm run test:ui          # Run tests with UI dashboard
npm run test:coverage    # Generate coverage report

# Performance Testing (k6)
npm run test:performance:v1    # Test v1 endpoint
npm run test:performance:v2    # Test v2 endpoint
npm run test:performance:load  # Full load test

# Code Quality
npm run lint             # Check linting
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier
npm run format:check     # Check formatting

🐳 Docker

The project uses Docker Compose profiles for managing development and production environments in a single configuration file.

Production Environment

# Start production stack (API + Prometheus + Grafana)
docker-compose --profile production up -d

# View logs
docker-compose logs -f api-prod

# Stop services
docker-compose --profile production down

Development Environment

# Start dev environment with hot reload
docker-compose --profile dev up -d

# View logs
docker-compose logs -f api-dev

# Stop services
docker-compose --profile dev down

Services

API: http://localhost:3000
Prometheus: http://localhost:9090
Grafana: http://localhost:3001 (admin/admin)

See DOCKER.md for complete documentation.

📡 API Endpoints

Health & Metrics

Liveness: GET /health/live - Is the app running?
Readiness: GET /health/ready - Can it serve traffic?
Metrics: GET /metrics - Prometheus metrics
Docs: GET /docs - Swagger UI

Greetings API (v1)

Get Greeting: GET /api/v1/greetings

Greetings API (v2)

Get Greeting (enhanced): GET /api/v2/greetings

API Versioning: Multiple versions coexist, sharing the same domain layer but with different use cases.

🧪 Testing

Comprehensive Test Suite

The project includes 244 tests across all layers with excellent coverage:

Coverage Stats (as of v2.1.0):

✅ Statements: 98.42%
✅ Branches: 84.00%
✅ Functions: 96.87%
✅ Lines: 98.38%

Coverage Thresholds: 80% minimum for all metrics

Unit Tests

Test business logic in isolation:

npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:ui          # Interactive UI dashboard
npm run test:coverage    # Generate coverage report

Test Coverage by Layer:

Domain Layer (Pure business logic):

DomainEvent.spec.ts - Base domain event class (12 tests)
GreetingCreatedEvent.spec.ts - Greeting domain event (21 tests)
Greeting.spec.ts - Greeting entity
Message.spec.ts - Message value object

Application Layer (Use cases & orchestration):

GetGreetingUseCase.spec.ts (v1 and v2) - Business workflows (19 tests each)
GreetingMapper.spec.ts (v1 and v2) - Data transformations (29 tests v2)
GreetingCreatedEventHandler.spec.ts - Event handling (13 tests)
InMemoryDomainEventPublisher.spec.ts - Event publishing (29 tests)

Infrastructure Layer (Repositories):

InMemoryGreetingRepository.spec.ts - Data persistence (19 tests)

Architecture Principle: Infrastructure adapters (controllers, middlewares, plugins, route loaders) are excluded from unit test coverage as they're validated through integration/E2E tests. This aligns with Hexagonal Architecture best practices.

Integration Tests

Test HTTP endpoints and infrastructure:

describe("GET /api/v1/greetings", () => {
  it("should return greeting", async () => {
    const response = await request(app.server)
      .get("/api/v1/greetings")
      .expect(200);
    expect(response.body.message).toBe("Hello World!");
  });
});

Integration Test Coverage:

HTTP endpoints (v1 and v2)
Rate limiting
Health checks
Metrics collection
Error handling

Performance Tests (k6)

Load testing with strict performance thresholds:

npm run test:performance:v1     # Test v1 endpoint
npm run test:performance:v2     # Test v2 endpoint
npm run test:performance:load   # Full load test

Performance Thresholds:

p95 latency < 500ms
p99 latency < 1000ms
Error rate < 1%
Request rate > 50 req/s

See test/performance/README.md

Contract Tests (Pact)

Consumer-driven contract testing ensures API compatibility:

npm run test:contract:provider

See test/contract/README.md

📊 Observability

Logging (Winston)

Structured JSON logging in production, pretty logs in development:

logger.info("Processing request", {
  requestId: request.id,
  version: "v1",
});

Metrics (Prometheus)

Available at /metrics:

http_request_duration_seconds - Request latency
http_requests_total - Total requests
http_requests_in_progress - Active requests

Health Checks

Liveness: /health/live - Basic health check
Readiness: /health/ready - Dependency health (memory, DB, etc.)

OpenAPI Documentation

Interactive API docs at:

Swagger UI: http://localhost:3000/docs

📚 Documentation

Core Documentation

SETUP.md - Initial setup guide after using this template (start here!)
ARCHITECTURE.md - Complete architecture guide (Hexagonal + DDD + Vertical Slices)
DOCKER.md - Docker setup, multi-stage builds, and Docker Compose
GITHUB_ACTIONS.md - CI/CD pipeline, workflows, and automation
CLAUDE.md - Development guide for Claude Code AI assistant

Architecture Decision Records (ADRs)

Document key architectural decisions with context and consequences:

ADR Index - Complete list of architectural decisions
ADR-0001 - Hexagonal Architecture adoption
ADR-0007 - Bounded Contexts organization
ADR-0009 - OOP + FP hybrid approach

View all ADRs →

Testing Guides

Performance Testing - k6 load testing, thresholds, and automated test runner
Contract Testing - Provider - Pact provider tests for HTTP inbound adapters
Contract Testing - Consumer - Pact consumer tests reference (HTTP outbound adapters)
Contract Tests README - Contract testing overview and execution

Integration Guides

Database Integration - Prisma setup and repository implementation guide

Utility Scripts

Scripts README - Automated performance test runner documentation

🎯 Design Patterns

Dependency Injection (Awilix)
Factory Pattern (Entity creation)
Mapper Pattern (Domain ↔ DTO)
Repository Pattern (Data access)
Strategy Pattern (API versioning)

🔒 Security

Helmet security headers
CORS configuration
Input validation with Zod
Non-root Docker user
Environment variable validation

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Built with ❤️ using modern Node.js best practices
Inspired by Clean Architecture, DDD, and Hexagonal Architecture principles

Version: 2.1.0 Status: Production Ready Architecture: Hexagonal + Onion + Screaming Last Updated: December 2024

(⬆️ Back to top)