xpress-generator

Professional Express.js project generator. Scaffold a complete, production-ready backend in one command — clean architecture, auth, migrations, Docker, testing, and linting all wired up automatically.

npx xpress-generator create MyApp

Features

• Clean module architecture — src/modules/{name}/, src/shared/, src/middleware/ instead of scattered flat folders
• 4 databases — MongoDB, MySQL, PostgreSQL, SQL Server
• TypeScript optional — full .ts templates, tsconfig.json, ts-jest
• Auth included — JWT access tokens (15m) + refresh tokens (7d, httpOnly cookie)
• Role-based access — verifyToken + requireRole('admin') middleware
• Rate limiting — express-rate-limit on auth routes
• Centralized error handling — AppError, errorHandler, catchAsync
• Input validation — Zod schemas + reusable validate middleware
• Standard HTTP responses — httpResponse.success / created / paginated / noContent
• Migrations — Sequelize CLI for MySQL/PostgreSQL · custom SQL runner for SQL Server
• Docker ready — multi-stage Dockerfile + docker-compose.yml per database
• Multi-stage dependencies — prod / dev-runtime / testing clearly separated in package.json
• Testing ready — Jest + supertest, dedicated tests/setup.js, 70 % coverage threshold
• Linting — ESLint (+ @typescript-eslint for TS projects)
• Pre-commit hooks — Husky + lint-staged auto-configured
• Code generators — generate:model (full CRUD module) and generate:middleware

Quick Start

# Interactive — prompts all questions
npx xpress-generator create

# Or pass the project name directly
npx xpress-generator create MyApp

The CLI will ask:

1. Project name (PascalCase)
2. Database — MongoDB · MySQL · PostgreSQL · SQLServer
3. TypeScript? — Yes / No
4. Where to save — Current directory · Desktop · Downloads · Documents · Custom path

Generated Project Structure

MyApp/
├── src/
│   ├── app.js / app.ts               ← Express app (exported, no listen)
│   ├── server.js / server.ts         ← Entry point — app.listen()
│   ├── config/
│   │   └── config-{db}.js            ← Database connection
│   ├── shared/                       ← Reusable code shared across modules
│   │   ├── errors/
│   │   │   └── AppError.js
│   │   ├── utils/
│   │   │   ├── catchAsync.js
│   │   │   └── httpResponse.js
│   │   ├── constants/
│   │   │   ├── httpStatus.js
│   │   │   └── messages.js
│   │   └── validators/
│   │       ├── validate.js
│   │       └── exampleSchema.js
│   ├── middleware/
│   │   ├── auth.js                   ← verifyToken, requireRole, authRateLimiter
│   │   └── errorHandler.js
│   └── modules/
│       ├── {name}/                   ← Index module (your project name)
│       │   ├── controller.js
│       │   ├── routes.js
│       │   ├── {name}Model.js
│       │   └── service.js
│       └── auth/                     ← Auth module
│           ├── authController.js
│           ├── authRoutes.js
│           └── RefreshToken.js
├── db/                               ← Migrations (relational DBs only)
│   ├── migrations/
│   │   └── {timestamp}-create-{name}.js   ← or .sql for SQL Server
│   └── seeders/                      ← (MySQL / PostgreSQL)
├── tests/
│   ├── setup.js                      ← NODE_ENV=test, JWT secrets for testing
│   └── indexController.test.js
├── .env
├── .eslintrc.json
├── .gitignore
├── .husky/
│   └── pre-commit                    ← npx lint-staged
├── .lintstagedrc.json
├── .sequelizerc                      ← (MySQL / PostgreSQL only)
├── .xpress.json                      ← project metadata for generate commands
├── .dockerignore
├── Dockerfile                        ← Multi-stage build
├── docker-compose.yml                ← DB service + app
├── jest.config.js
└── package.json

TypeScript projects use .ts extensions, include tsconfig.json, and scripts use ts-node.

npm Scripts (generated project)

| Script | Description | |--------|-------------| | npm run dev | Start with nodemon (JS) or ts-node (TS) | | npm start | Start production server | | npm test | Run Jest with coverage | | npm run test:watch | Run Jest in watch mode | | npm run build | Compile TypeScript to dist/ (TS only) | | npm run db:migrate | Run pending migrations (relational DBs only) | | npm run db:migrate:undo | Roll back last migration (MySQL / PostgreSQL) |

CLI Commands

# Create a new project
npx xpress-generator create [name]

# Generate a full CRUD module (model + service + controller + routes + schema)
npx xpress-generator generate:model <ModelName>
npx xpress-generator g:model <ModelName>           # alias

# Generate a custom middleware
npx xpress-generator generate:middleware <name>
npx xpress-generator g:middleware <name>           # alias

generate:model output

Running xpress generate:model Product inside a project creates:

src/modules/product/
  ├── productModel.js       ← DB model (Mongoose / Sequelize / mssql)
  ├── service.js            ← getAll, getById, create, update, remove
  ├── schema.js             ← Zod validation schema
  ├── controller.js         ← CRUD handlers via catchAsync
  └── routes.js             ← Express router, auth-protected

db/migrations/{ts}-create-product.js   ← (MySQL / PostgreSQL)
db/migrations/{ts}-create-product.sql  ← (SQL Server)

Auth API

The generated project includes a ready-to-use auth layer:

| Method | Route | Description | |--------|-------|-------------| | POST | /api/auth/login | Returns accessToken + sets refreshToken cookie | | POST | /api/auth/refresh | Issues new accessToken from refresh cookie | | POST | /api/auth/logout | Revokes token from DB and clears cookie |

Configure in .env:

JWT_SECRET=your-access-secret
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_SECRET=your-refresh-secret

Migrations

MySQL / PostgreSQL (Sequelize CLI)

# Run all pending migrations
npm run db:migrate

# Roll back the last migration
npm run db:migrate:undo

Migration files are stored in db/migrations/ and tracked automatically by Sequelize CLI.

SQL Server

# Run all pending .sql files (tracked in _migrations table)
npm run db:migrate

Docker

# Start the full stack (app + database)
docker compose up

# Production build
docker compose up --build

# Detached mode
docker compose up -d

The generated Dockerfile uses multi-stage builds: the production image contains only production dependencies and compiled source — dev tools and test packages are never included.

Installed Dependencies

Production:

express  dotenv  colors  cors  helmet  morgan
bcryptjs  jsonwebtoken  zod  express-rate-limit  cookie-parser
+ DB driver (mongoose / mysql2+sequelize / pg+sequelize / mssql)

Dev — runtime:

nodemon
+ TypeScript: ts-node  typescript  @types/*

Dev — testing:

jest  supertest  eslint  lint-staged
+ TypeScript: ts-jest  @types/jest  @types/supertest

Dev — git hooks:

husky

Dev — migrations:

sequelize-cli   (MySQL / PostgreSQL only)

Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0

License

MIT © Felipe Vargas