🔥 microforge

CLI to generate Node.js microservices with Express, Docker, health checks, graceful shutdown, smart templates and a non-interactive mode for CI/CD. CLI para generar microservicios Node.js con Express, Docker, health checks, graceful shutdown, plantillas inteligentes y modo no interactivo para CI/CD.

🇺🇸 English

Overview

microforge is a CLI that creates Node.js microservices with a clean structure, base files, optional dependencies, Docker support, and smart templates for common services.

Current version: 5.0.0

What's new in 5.0.0

• Non-interactive mode with --yes and flags (--port, --template, --extras, --path, --install/--no-install, --git/--no-git)
• microforge list command to inspect templates and extras
• Auto update check: the CLI notifies you when a new version is published to npm
• Pinned real versions in generated package.json (no more "latest")
• Random JWT_SECRET generated per service (no more hardcoded secrets)
• Service name is validated and sanitized
• Graceful shutdown on SIGTERM / SIGINT + handlers for unhandledRejection/uncaughtException
• Centralized errorHandler + notFoundHandler middleware wired into the generated app
• Multi-stage Dockerfile running as non-root node user with tini and HEALTHCHECK
• .dockerignore + .env.example generated for every service
• docker-compose.yml now provisions MongoDB or MySQL automatically when those extras are selected
• New optional extras: compression, express-rate-limit, pino (logger)
• Optional git init + initial commit
• Per-service README.md generated inside each microservice

Installation

Run without global install

npx microforge@latest

Install globally

npm install -g microforge

Then run:

microforge

Quick start

Interactive wizard

microforge create auth-service

You'll be prompted for port, optional extras, install, git init and location.

Non-interactive (great for scripts / CI)

microforge create users-service --yes \
  --port 4002 \
  --extras cors,helmet,pino \
  --template users \
  --install --git

Or just accept every default:

microforge create my-service --yes

List available templates and extras

microforge list

CLI reference

microforge create <service-name> [options]
microforge [options]
microforge list

Options

| Option | Description | Default | | --- | --- | --- | | --port <number> | Service port (1–65535) | 4001 | | --template <name> | Force template: base, auth, users, products | auto-detected from name | | --extras <list> | Comma-separated extras | none | | --path <path> | Base folder where the service will be created | current directory | | --install / --no-install | Run npm install automatically | asked / true with --yes | | --git / --no-git | Run git init + initial commit | asked / false with --yes | | -y, --yes | Skip prompts, use defaults + flags | false |

Available extras

cors, mongoose, mysql2, morgan, helmet, compression, express-rate-limit, pino

Smart templates

The template is auto-detected from the service name (e.g. auth-service → auth, users-service → users, products-service → products). You can override with --template.

Auth

microforge create auth-service

Creates:

• POST /auth/register
• POST /auth/login
• GET /auth/me (requires Bearer token)
• verifyToken middleware
• bcrypt, jsonwebtoken
• Random JWT_SECRET in .env

Users

microforge create users-service

CRUD /users (all routes require Bearer token) + verifyToken, bcrypt, jsonwebtoken.

Products

microforge create products-service

CRUD /products.

Generated structure

my-service/
├── .dockerignore
├── .env
├── .env.example
├── .gitignore
├── Dockerfile
├── README.md
├── docker-compose.yml
├── package.json
└── src/
    ├── app.js
    ├── server.js
    ├── config/
    ├── controllers/
    ├── middlewares/
    │   └── errorHandler.js
    ├── models/
    ├── routes/
    ├── services/
    └── utils/

Every generated service includes:

• GET / — service info
• GET /health — health check (also used by Docker HEALTHCHECK)
• Centralized error handler + 404 handler
• Graceful shutdown (SIGTERM/SIGINT)

Docker

Multi-stage build with non-root node user, tini as PID 1, and a HEALTHCHECK that pings /health.

docker compose up --build

If you select mongoose, the compose file provisions MongoDB 7 automatically (and wires MONGO_URI). If you select mysql2, it provisions MySQL 8 and wires the MYSQL_* environment variables.

Example workflows

Full non-interactive auth microservice with MongoDB, rate limiting and pino logger:

microforge create auth-service --yes \
  --port 5000 \
  --template auth \
  --extras cors,helmet,mongoose,express-rate-limit,pino \
  --install --git

Basic interactive wizard:

microforge

Notes

• Generated templates use in-memory arrays as a simple starting point — swap them for real persistence (Mongoose/Knex/Prisma) when ready.
• Pinned dependency versions are bundled with the CLI. They are sensible defaults; upgrade them inside each service as needed.

Roadmap

• TypeScript flag (--ts)
• Auto-generated tests (Vitest)
• Zod/Joi request validation
• New templates: gateway, queue, uploads, notifications
• Custom/user templates from ~/.microforge/templates

Author

Created by Javier Carrizo

🇪🇸 Español

Descripción

microforge es un CLI para crear microservicios Node.js con una estructura limpia, archivos base, dependencias opcionales, soporte Docker y plantillas inteligentes para servicios comunes.

Versión actual: 5.0.0

Novedades en 5.0.0

• Modo no interactivo con --yes y flags (--port, --template, --extras, --path, --install/--no-install, --git/--no-git)
• Comando microforge list para ver templates y extras disponibles
• Aviso automático de updates: el CLI te avisa cuando hay una versión nueva en npm
• Versiones reales fijadas en el package.json generado (chau "latest")
• JWT_SECRET aleatorio generado por servicio (se acabó la clave hardcodeada)
• El nombre del servicio se valida y sanitiza
• Graceful shutdown con SIGTERM/SIGINT + handlers para unhandledRejection/uncaughtException
• Middleware errorHandler + notFoundHandler centralizados ya conectados en la app
• Dockerfile multi-stage corriendo como usuario no-root node con tini y HEALTHCHECK
• .dockerignore + .env.example generados automáticamente
• El docker-compose.yml ahora levanta MongoDB o MySQL si elegís esos extras
• Nuevos extras opcionales: compression, express-rate-limit, pino (logger)
• git init + commit inicial opcional
• README.md por servicio generado dentro de cada microservicio

Instalación

Usarlo sin instalar globalmente

npx microforge@latest

Instalarlo globalmente

npm install -g microforge

Después ejecutarlo con:

microforge

Uso rápido

Wizard interactivo

microforge create auth-service

Te va a preguntar puerto, extras, instalación, git y ubicación.

No interactivo (ideal para scripts / CI)

microforge create users-service --yes \
  --port 4002 \
  --extras cors,helmet,pino \
  --template users \
  --install --git

O usando todos los defaults:

microforge create mi-servicio --yes

Listar templates y extras disponibles

microforge list

Referencia del CLI

microforge create <service-name> [opciones]
microforge [opciones]
microforge list

Opciones

| Opción | Descripción | Default | | --- | --- | --- | | --port <number> | Puerto del servicio (1–65535) | 4001 | | --template <name> | Forzar template: base, auth, users, products | autodetectado por nombre | | --extras <list> | Extras separados por coma | ninguno | | --path <path> | Carpeta base donde crear el servicio | directorio actual | | --install / --no-install | Ejecutar npm install automáticamente | se pregunta / true con --yes | | --git / --no-git | Ejecutar git init + commit inicial | se pregunta / false con --yes | | -y, --yes | Saltear prompts y usar defaults + flags | false |

Extras disponibles

cors, mongoose, mysql2, morgan, helmet, compression, express-rate-limit, pino

Plantillas inteligentes

El template se detecta automáticamente por el nombre (auth-service → auth, users-service → users, products-service → products). Podés forzarlo con --template.

Auth

microforge create auth-service

Crea:

• POST /auth/register
• POST /auth/login
• GET /auth/me (requiere Bearer token)
• middleware verifyToken
• bcrypt, jsonwebtoken
• JWT_SECRET aleatorio en .env

Users

microforge create users-service

CRUD /users (todas las rutas requieren Bearer token) + verifyToken, bcrypt, jsonwebtoken.

Products

microforge create products-service

CRUD /products.

Estructura generada

mi-servicio/
├── .dockerignore
├── .env
├── .env.example
├── .gitignore
├── Dockerfile
├── README.md
├── docker-compose.yml
├── package.json
└── src/
    ├── app.js
    ├── server.js
    ├── config/
    ├── controllers/
    ├── middlewares/
    │   └── errorHandler.js
    ├── models/
    ├── routes/
    ├── services/
    └── utils/

Cada servicio generado incluye:

• GET / — info del servicio
• GET /health — health check (también usado por el HEALTHCHECK del Docker)
• error handler y 404 handler centralizados
• Graceful shutdown (SIGTERM/SIGINT)

Docker

Build multi-stage con usuario no-root node, tini como PID 1, y un HEALTHCHECK que pega contra /health.

docker compose up --build

Si elegís mongoose, el compose levanta MongoDB 7 automáticamente (y completa MONGO_URI). Si elegís mysql2, levanta MySQL 8 y configura las variables MYSQL_*.

Ejemplos de flujo

Microservicio de auth completo con MongoDB, rate limiting y pino, sin preguntas:

microforge create auth-service --yes \
  --port 5000 \
  --template auth \
  --extras cors,helmet,mongoose,express-rate-limit,pino \
  --install --git

Wizard básico interactivo:

microforge

Notas

• Las plantillas actuales usan arrays en memoria como punto de partida simple: cambialas por persistencia real (Mongoose/Knex/Prisma) cuando lo necesites.
• Las versiones de dependencias van fijadas dentro del CLI. Son defaults razonables; actualizá dentro de cada servicio cuando haga falta.

Roadmap

• Flag TypeScript (--ts)
• Tests autogenerados (Vitest)
• Validación de requests con Zod/Joi
• Nuevas plantillas: gateway, queue, uploads, notifications
• Templates propios del usuario en ~/.microforge/templates

Autor

Creado por Javier Carrizo