api-generator

Scaffold a production-minded Node.js + TypeScript + Express microservice with logging, health, metrics, tracing, tests, and Docker.

Install

npm install -g api-generator

Usage

# create in current directory, with hello endpoint
api-generator

# create in provided directory with users endpoint
api-generator users --dir ./users-service

# choose package manager
api-generator products --dir ./products-service --package-manager pnpm

Features

• Express + TypeScript boilerplate with versioned routes (/api/v1)
• Logging with Winston, request-id correlation
• Health endpoints: /healthz, /readyz
• Prometheus metrics at /metrics
• OpenTelemetry tracing (gated via env)
• Zod env validation and request validation helper
• Vitest + MSW + Supertest tests
• Dockerfile (multi-stage, non-root, HEALTHCHECK) + .dockerignore
• Config via config/ and .env (dotenv prewired)

How to use

1) Generate a service

# hello default
api-generator --dir ./hello-service

# custom endpoint
api-generator users --dir ./users-service

2) Install and run

cd ./users-service
npm install
cp env.example .env
npm run dev

Test endpoints:

curl http://localhost:3000/healthz
curl http://localhost:3000/readyz
curl http://localhost:3000/metrics
curl "http://localhost:3000/api/v1/users?limit=5"

3) Add a database (optional)

See the generated service README.md for Postgres integration using Prisma, TypeORM, or Sequelize, plus docker-compose.

4) Run tests

npm test

5) Build and publish Docker image

# build image (from generated service directory)
docker build -t myorg/users-service:0.1.0 .

# run locally
docker run --rm -p 3000:3000 --env-file ./.env myorg/users-service:0.1.0

# push to registry
docker tag myorg/users-service:0.1.0 ghcr.io/myorg/users-service:0.1.0
docker push ghcr.io/myorg/users-service:0.1.0

Notes:

• Container runs as non-root and exposes /healthz for HEALTHCHECK.
• Enable tracing by setting OTEL_ENABLED=true and optionally OTEL_EXPORTER_OTLP_ENDPOINT.

License

MIT