Skip to main content

Getting Started

Prerequisites​

Before you begin, make sure you have:

  • Node.js >= 18.0.0 — Download
  • npm >= 8.0.0 (included with Node.js)
  • A running database or Docker installed (to spin one up with docker compose up)

Create your first project​

Run the following command — no global install required:

npx xpress-generator create

Or pass the project name directly to skip the first prompt:

npx xpress-generator create MyApp

Interactive prompts​

The CLI will ask you four questions:

? Project name (PascalCase): MyApp
? What database will you use? MongoDB
? Use TypeScript? No
? Where to save the project? Current directory (.)
PromptOptions
Project nameAny PascalCase string (e.g. MyApp, BlogApi)
DatabaseMongoDB · MySQL · PostgreSQL · SQLServer
TypeScriptYes / No (default: No)
Save locationCurrent directory (.) · Desktop · Downloads · Documents · Custom path
Scaffold into any folder

Select "Ruta actual (.)" to create the project inside the directory you're already in. Ideal for CI workflows or when you've already created the folder.

After answering, the CLI automatically:

  1. Generates the full project structure
  2. Runs npm init -y
  3. Installs production dependencies
  4. Installs dev-runtime dependencies (nodemon, TypeScript tools if applicable)
  5. Installs testing dependencies (jest, supertest, eslint, etc.)
  6. Installs husky and configures pre-commit hooks
  7. Installs migration tools (sequelize-cli for MySQL/PostgreSQL)

This takes approximately 2–4 minutes depending on your connection.

Start developing​

cd MyApp

Configure your environment​

Open .env and fill in your database credentials and secrets:

PORT=3000
NODE_ENV=development

# JWT
JWT_SECRET=replace-with-a-strong-random-secret
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_SECRET=replace-with-another-strong-secret

# MongoDB example
MONGO_URI=mongodb://localhost:27017/myapp
info

The .env file is pre-generated with placeholder values tailored to your chosen database. See Environment Variables for the full reference.

Option A — Run with Node.js directly​

Make sure your database is already running, then:

npm run dev

Your server starts on http://localhost:3000.

Option B — Run with Docker (recommended)​

No database setup needed — Docker starts everything:

docker compose up

This starts both the app (with hot-reload in dev mode) and a database container. The docker-compose.yml is pre-configured for your chosen DB with healthchecks and named volumes.

TypeScript projects

For TypeScript, npm run dev uses ts-node src/server.ts. To compile for production, run npm run build which outputs to dist/.

Run migrations (MySQL / PostgreSQL / SQL Server)​

If you chose a relational database, run the initial migration to create the tables:

npm run db:migrate

This runs npx sequelize-cli db:migrate (MySQL/PostgreSQL) or node db/migrate.js (SQL Server) and creates the tables defined in db/migrations/.

MongoDB

MongoDB is schema-less — no migrations needed. Mongoose creates collections automatically when you insert the first document.

Verify it works​

Health check​

curl http://localhost:3000/

Expected response:

{
  "status": "success",
  "data": {
    "message": "¡Bienvenido a la API de MyApp!"
  }
}

Auth routes​

# Login
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"secret123"}'

Run the tests​

npm test

The generated project includes an integration test (tests/indexController.test.js) and a dedicated test setup file (tests/setup.js) that automatically sets NODE_ENV=test and test JWT secrets before each suite runs.

The test verifies:

  • GET / returns 200 with status: "success"
  • Unknown routes return 404 with status: "fail"
  • The auth route exists and responds

Run tests in watch mode during development:

npm run test:watch

Project structure overview​

MyApp/
├── src/
│   ├── app.js                  ← Express app (exported for testing)
│   ├── server.js               ← Entry point — app.listen()
│   ├── config/                 ← Database connection
│   ├── shared/                 ← Shared utilities across all modules
│   │   ├── errors/             ← AppError class
│   │   ├── utils/              ← catchAsync, httpResponse
│   │   ├── constants/          ← HTTP status codes & message strings
│   │   └── validators/         ← Zod schemas & validate middleware
│   ├── middleware/             ← auth.js, errorHandler.js
│   └── modules/
│       ├── {name}/             ← Your project's index module
│       └── auth/               ← Auth module
├── db/
│   └── migrations/             ← Versioned migration files
├── tests/
│   ├── setup.js                ← Test environment config
│   └── indexController.test.js
├── Dockerfile                  ← Multi-stage build
├── docker-compose.yml
├── .sequelizerc                ← (MySQL / PostgreSQL only)
└── jest.config.js
.xpress.json

This file stores project metadata (dbType, language, version). It is used by the generate:model and generate:middleware commands to know which templates to use.

Next steps​