Code / express-boilerplate

express-boilerplate

TypeScript · 50 files · main @ 81e924d

Files

  • scripts/
  • src/
  • tests/
  • .env.example
  • .gitignore
  • .yarnrc.yml
  • biome.json
  • docker-compose.yml
  • Dockerfile
  • LICENSE
  • package.json
  • README.md
  • tsconfig.build.json
  • tsconfig.json
  • vitest.config.ts

README

Express API Starter

A production-minded Express 5 + TypeScript starter that is still small enough to understand without consulting an archaeologist.

Top-level dependency versions are pinned to the latest releases verified on July 14, 2026. Regenerate yarn.lock with yarn install on first use.

Included

  • Express 5 and TypeScript
  • Yarn 4.17.1 pinned through the packageManager field
  • Versioned routes under /api/v1
  • Controllers, services, validation, repositories, and route modules
  • JWT access + refresh tokens using jose
  • HTTP-only refresh-token cookies and token-version based revocation/rotation
  • Password hashing with bcryptjs
  • MongoDB connector using Mongoose
  • SQL connector using Sequelize, with PostgreSQL, MySQL, MariaDB, and MSSQL drivers
  • In-memory repository for running immediately without a database
  • Zod environment and request validation
  • Pino structured logging with sensitive-field redaction
  • Helmet, CORS, HPP, compression, body limits, and rate limiting
  • Central error handling and 404 handling
  • OpenAPI docs at /docs
  • Vitest + Supertest tests
  • Dockerfile and Docker Compose for PostgreSQL and MongoDB
  • Module generator: yarn generate:module products

Start

cp .env.example .env
corepack enable
yarn install
# Commit the generated yarn.lock after the first install.
yarn dev

Open:

  • API: http://localhost:3000/api/v1
  • Health: http://localhost:3000/health
  • Docs: http://localhost:3000/docs

The default DATABASE_DRIVER=none uses memory, so registration and login work immediately. Data disappears after restart, because RAM remains stubbornly non-persistent.

Choose a database

MongoDB

docker compose up -d mongo

Set:

DATABASE_DRIVER=mongo
MONGO_URI=mongodb://localhost:27017/express_api_starter

PostgreSQL

docker compose up -d postgres

Set:

DATABASE_DRIVER=sql
SQL_DIALECT=postgres
SQL_SYNC=true

SQL_SYNC=true is only a local-development convenience. Use migrations in production.

API examples

Register:

curl -i http://localhost:3000/api/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","password":"SecurePass123"}'

Login:

curl -i http://localhost:3000/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"ada@example.com","password":"SecurePass123"}'

Use the returned access token:

curl http://localhost:3000/api/v1/users/me \
  -H 'authorization: Bearer YOUR_ACCESS_TOKEN'

Refresh uses the HTTP-only cookie returned by register/login:

curl -i -X POST http://localhost:3000/api/v1/auth/refresh \
  --cookie 'refresh_token=YOUR_REFRESH_TOKEN'

Generate a module

yarn generate:module products

This creates controller, service, routes, and validation files, then registers the router automatically in src/routes/index.ts.

Project structure

src/
├── app.ts
├── server.ts
├── common/
│   ├── errors/
│   ├── types/
│   └── utils/
├── config/
├── database/
│   ├── mongo/
│   └── sql/
├── docs/
├── middleware/
├── modules/
│   ├── auth/
│   ├── health/
│   └── users/
└── routes/

Removing what you do not need

Remove MongoDB

Delete src/database/mongo, remove mongoose from package.json, and remove the Mongo service from docker-compose.yml.

Remove SQL

Delete src/database/sql, remove sequelize and the unused SQL drivers from package.json, and remove the PostgreSQL service from docker-compose.yml.

You may also keep Sequelize but delete drivers for databases you will never use:

  • PostgreSQL: pg, pg-hstore
  • MySQL: mysql2
  • MariaDB: mariadb
  • MSSQL: tedious

Remove Swagger UI

Delete src/docs, remove the docs mount from src/app.ts, and remove swagger-ui-express plus its type package.

Security notes

  • Replace both JWT secrets before deploying.
  • Use HTTPS and set COOKIE_SECURE=true in production.
  • Keep access tokens short-lived.
  • The refresh flow rotates tokenVersion; an old refresh token becomes invalid after a successful refresh.
  • For multi-device sessions, store hashed refresh-token records per device instead of a single user-level token version.
  • Configure TRUST_PROXY=true only behind a trusted reverse proxy.
  • Replace SQL_SYNC with migrations before production.
  • Restrict CORS origins. Wildcard CORS and credentials are a famously bad marriage.
  • If you set COOKIE_SAME_SITE=none, add CSRF protection for cookie-authenticated endpoints.

Commands

yarn dev
yarn build
yarn start
yarn typecheck
yarn check
yarn check:fix
yarn test
yarn generate:module orders