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
packageManagerfield - 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=truein 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=trueonly behind a trusted reverse proxy. - Replace
SQL_SYNCwith 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