Express + TypeScript Backend Starter

Production-ready starter template for building APIs with Express 5 and TypeScript. It includes authentication with JWT access/refresh tokens, Prisma ORM, Zod validation, Swagger docs, security middleware, logging, and opinionated tooling.

Features

• Express 5 + TypeScript with strict compiler options
• Authentication: JWT access tokens + HTTP-only cookie refresh tokens
• Password hashing: argon2
• Database: Prisma ORM (PostgreSQL)
• Validation: Zod schemas and a reusable validation middleware
• API Docs: Swagger (OpenAPI) via swagger-jsdoc and swagger-ui-express
• Security: Helmet, rate limiting, compression, CORS
• Error handling: Centralized error middleware and graceful shutdown
• Logging: Winston console logger
• Tooling: ESLint + Prettier, scripts for dev/build/start

Project Structure

backend/
  src/
    config/        # prisma client, swagger setup
    controllers/   # route handlers
    middleware/    # auth, validation, error, refresh-token
    routes/        # route definitions
    types/         # request/response types (e.g., AuthRequest)
    utils/         # hash, jwt, logger
    validators/    # zod schemas
    index.ts       # app entry
  prisma/
    schema.prisma
    migrations/
  docs/
    API.md         # expanded API guide

Requirements

• Node.js 18+
• PostgreSQL database

Database Management

This starter works with any PostgreSQL database. If you use Supabase as your Postgres host:

• Set DATABASE_URL in backend/.env to your Supabase connection string
• You can manage schema in one of two ways:

Schema management options:

1. Prisma manages migrations (applied to Supabase)

cd backend
# Edit prisma/schema.prisma
npx prisma migrate dev --name <change-name>
npx prisma generate

Use this if you want this repo to be the source of truth for DB schema. Commit the prisma/migrations/ folder.

2. Supabase manages schema

cd backend
npx prisma db pull   # pull schema from Supabase into schema.prisma
npx prisma generate  # generate client; safe, no DB changes

Getting Started

git clone https://github.com/rafayhanan/Backend-Boilerplate.git
cd backend
npm install

Create an .env file in backend/ (example values shown):

DATABASE_URL=postgresql://user:password@localhost:5432/yourdb
DIRECT_URL=postgresql://user:password@localhost:5432/yourdb

ACCESS_TOKEN_SECRET=change-me
REFRESH_TOKEN_SECRET=change-me

PORT=5000

Initialize the database (generate client and apply migrations):

npx prisma migrate dev --name init

Run in development:

npm run dev
# Swagger UI: http://localhost:3000/api-docs

Build and run in production:

npm run build
npm start

NPM Scripts

• npm run dev – Run with ts-node-dev (watch mode)
• npm run build – TypeScript compile to dist/
• npm start – Run compiled app from dist/
• npm run lint – Lint with ESLint
• npm run format – Format with Prettier

Config Notes

• Refresh tokens are stored on the User model and set as an HTTP-only cookie named refreshToken.
• If your frontend runs on a different origin, configure CORS and cookie attributes (sameSite, secure) accordingly.

API Documentation

• High-level usage in this README
• Detailed endpoints: see docs/API.md or Swagger at /api-docs when the server is running

Contributing

Contributions are welcome!

• Fork the repo and create a feature branch: git checkout -b feat/your-feature
• Install dependencies and run locally: npm install then npm run dev
• Ensure code is formatted and linted: npm run format && npm run lint
• Include concise descriptions in PRs.