TypeScript Express Boilerplate

A production-ready TypeScript/Express API server with PostgreSQL database integration, type-safe API contracts, and automated OpenAPI documentation generation.

Architecture

Features

• Type-Safe Configuration — Zod-based environment variable validation with fail-fast startup
• Database — PostgreSQL with Sequelize ORM and migration support
• API Contracts — Type-safe API definitions using @ts-rest and Zod schemas
• Auto-Generated Docs — Interactive API documentation via Scalar UI at /reference
• Structured Logging — Winston logger with multiple transports
• Code Quality — Biome for linting and formatting
• Observability — New Relic APM integration for monitoring

Tech Stack

Category	Technology
Runtime	Node.js with TypeScript 5.9.2
Framework	Express 4.18.0
Database	PostgreSQL with Sequelize 6.37.7
Validation	Zod 3.20.0
API Contracts	@ts-rest 3.52.1
Logging	Winston 3.17.0
Code Quality	Biome 0.3.3

Prerequisites

• Node.js (latest LTS recommended)
• PostgreSQL database
• Redis (optional, for caching)

Installation

1. Clone the repository

git clone https://github.com/hemanth5544/boiler-plate.git
cd boiler-plate

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env.dev

Configure the following required variables in .env.dev:

Server Configuration

PRIMARY_ENV=development
HOST_NAME=localhost
SERVER_PORT=8080
SERVER_READ_TIMEOUT=30000
SERVER_WRITE_TIMEOUT=30000
SERVER_IDLE_TIMEOUT=60000
SERVER_CORS_ALLOWED_ORIGINS=http://localhost:3000

Database Configuration

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password
DATABASE_NAME=your_database
DATABASE_SSL_MODE=disable
DATABASE_MAX_OPEN_CONNS=25
DATABASE_MAX_IDLE_CONNS=5
DATABASE_CONN_MAX_LIFETIME=300000
DATABASE_CONN_MAX_IDLE_TIME=60000
DATABASE_DIALECT=postgres

Authentication

AUTH_SECRET_KEY=your_secret_key_here

Optional Integrations

# Email Service
INTEGRATION_RESEND_API_KEY=your_resend_api_key

# Redis
REDIS_ADDRESS=localhost:6379
REDIS_PASSWORD=

# AWS S3
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_UPLOAD_BUCKET=your_bucket_name
AWS_ENDPOINT_URL=

Observability

NEW_RELIC_APP_NAME=your_app_name
OBSERVABILITY_ENVIRONMENT=development
OBSERVABILITY_LOGGING_LEVEL=info
OBSERVABILITY_LOGGING_FORMAT=json
OBSERVABILITY_LOGGING_SLOW_QUERY_THRESHOLD=1000
NEW_RELIC_LICENSE_KEY=your_license_key
NEW_RELIC_APP_LOG_FORWARDING_ENABLED=true
NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true
NEW_RELIC_DEBUG_LOGGING=false

4. Run database migrations

npm run db:migrate

Running the Application

Development Mode

Start the development server with hot-reload:

npm run dev

The server will start at http://localhost:8080 with hot-reload enabled using nodemon and ts-node.

Production Mode

Build and run the production server:

npm run build
npm start

Available Scripts

Script	Command	Description
dev	npm run dev	Start development server with hot-reload
build	npm run build	Compile TypeScript to JavaScript
start	npm start	Run production server
generate	npm run generate	Generate OpenAPI documentation
db:migrate	npm run db:migrate	Run database migrations
db:migrate:undo	npm run db:migrate:undo	Undo last migration
db:migrate:undo:all	npm run db:migrate:undo:all	Undo all migrations
db:seed	npm run db:seed	Run database seeders
db:seed:undo	npm run db:seed:undo	Undo all seeders
db:migration:generate	npm run db:migration:generate	Generate new migration file
lint	npm run lint	Lint code with Biome
format	npm run format	Format code with Biome
lint:fix	npm run lint:fix	Fix linting issues (unsafe)

Project Structure

boiler-plate/
├── server/
│   ├── api-docs/          # OpenAPI generation scripts
│   ├── config/            # Configuration management
│   ├── database/          # Database connection singleton
│   ├── handlers/          # Request handlers
│   ├── health/            # Health check utilities
│   ├── logger/            # Winston logger setup
│   ├── models/            # Sequelize models
│   ├── repository/        # Data access layer
│   ├── routes/            # Express routers
│   ├── services/          # Business logic
│   ├── zod/               # Validation schemas
│   └── server.ts          # Application entry point
├── migrations/            # Database migrations
├── .env.example           # Environment variables template
├── package.json           # Project dependencies
└── tsconfig.json          # TypeScript configuration

API Documentation

Once the server is running, visit http://localhost:8080/reference to access the interactive API documentation powered by Scalar UI.

The documentation is auto-generated from Zod schemas and @ts-rest contracts.

To regenerate the documentation:

npm run generate

Database Migrations

Create a new migration

npm run db:migration:generate -- migration-name

Run migrations

npm run db:migrate

Rollback migrations

# Undo last migration
npm run db:migrate:undo

# Undo all migrations
npm run db:migrate:undo:all

The boilerplate includes an example users table migration to get you started.

Health Check

The application exposes a health check endpoint at /status that returns:

• Overall system status (healthy/unhealthy)
• Database connectivity status
• Redis connectivity status (if configured)
• Response times for each service

Example response:

{
  "status": "healthy",
  "services": {
    "database": {
      "status": "healthy",
      "responseTime": "15ms"
    },
    "redis": {
      "status": "healthy",
      "responseTime": "5ms"
    }
  }
}

Code Quality

The project uses Biome for linting and formatting with the following configuration:

• Tab indentation
• Semicolons enforced
• Single quotes
• Line width: 100 characters

Run linting and formatting:

# Check for issues
npm run lint

# Format code
npm run format

# Auto-fix issues (unsafe)
npm run lint:fix