WestJS Documentation

Non-interactive examples

npx west-js-app --yes --name my-api

npx west-js-app --yes --name my-api --database prisma --db-provider postgresql --docker --package-manager pnpm

npx west-js-app --yes --name my-api --database drizzle --db-provider sqlite --no-docker

npx west-js-app --yes --name my-api --database typeorm --db-provider mysql --docker

src/app.ts — Express Application Factory

Creates and exports the Express app. Applies JSON body parsing, URL-encoded parsing, CORS (via cors), security headers (via helmet), HTTP request logging (via pino-http), rate limiting, and mounts all routers. The app is exported separately from the server so it can be imported in tests without binding a port.

• helmet() sets secure HTTP headers (XSS, clickjacking, MIME sniffing protection)
• cors() is configured with permissive defaults — tighten in production
• pino-http logs every request/response with duration and status code
• express.json() + express.urlencoded() parse incoming request bodies
• rateLimiter middleware is applied globally before routes
• Routes are mounted under their respective prefixes (/health, /api/examples)

src/server.ts — HTTP Server Entrypoint

Imports the app, binds it to the port from env, and registers SIGTERM/SIGINT handlers for graceful shutdown. When TypeORM is selected, the server waits for initializeDatabase() to resolve before binding the port — preventing requests before the DB connection is ready.

• Reads PORT from the validated env config (defaults to 3000)
• Logs the running port and NODE_ENV with pino
• SIGTERM / SIGINT close the HTTP server then destroy the DB connection (TypeORM)
• TypeORM variant calls initializeDatabase() before app.listen()

src/config/env.ts — Environment Variable Validation

Uses Zod to parse process.env at startup. If a required variable is missing or the wrong type, the process exits immediately with a readable error — preventing silent misconfiguration in production.

// Shape of the parsed env object
{
  NODE_ENV: 'development' | 'production' | 'test',
  PORT: number,              // coerced from string
  RATE_LIMIT_WINDOW_MS: number,
  RATE_LIMIT_MAX: number,
  DATABASE_URL: string       // only present when a DB is selected
}

src/lib/errors.ts — Error Classes

Exports AppError (base class with statusCode and isOperational flag) and HTTP-specific subclasses like NotFoundError (404) and ValidationError (422). Throwing these anywhere in the app causes the error handler middleware to produce a consistent JSON response.

• AppError extends Error — carry statusCode and message
• Operational errors (AppError subclasses) return JSON responses
• Non-operational errors (programming bugs) log full stack and return 500
• isOperational flag lets you distinguish expected vs unexpected failures

src/lib/logger.ts — Pino Logger

Creates a named pino logger instance. In development (NODE_ENV !== production) pino-pretty is used for human-readable, coloured log output. In production, plain JSON logs are emitted for log aggregation tools.

• Log level auto-set to 'debug' in development, 'info' in production
• pino-pretty provides coloured, formatted output during local development
• Structured JSON logs in production work with Datadog, Loki, CloudWatch etc.

src/middleware/error-handler.ts — Error Handler

Express error-handling middleware (4-argument signature). Catches all errors thrown or passed to next(). Operational AppError instances are returned as JSON with their statusCode. Everything else returns 500 and logs the full error details server-side.

// Response shape for all errors
{ "error": { "message": "Not found", "status": 404 } }

src/middleware/validate.ts — Zod Validation Middleware

A middleware factory: validate(schema) returns an Express RequestHandler that parses req.body against the given Zod schema. On failure it calls next() with a ValidationError (422). On success it replaces req.body with the parsed (type-safe) value.

// Usage in a route
router.post('/', validate(CreateItemSchema), createItem);

src/middleware/rate-limit.ts — Rate Limiter

Configures express-rate-limit using RATE_LIMIT_WINDOW_MS and RATE_LIMIT_MAX from the validated env. Exceeding the limit returns a 429 Too Many Requests response in standard JSON format.

• Window: 900000 ms (15 minutes) by default — change in .env
• Max requests per window: 100 by default
• Response after limit: { error: 'Too many requests' }

What the CLI generates

• prisma/schema.prisma — generator block with output pointing to src/generated/prisma
• prisma.config.ts — Prisma 7 defineConfig() with dotenv + datasource URL
• src/lib/prisma.ts — PrismaClient instantiated with the correct driver adapter
• src/db/index.ts — re-exports db for use across the project
• src/db/schema.ts — example User model to get started

Driver adapters per provider

First-run workflow

What the CLI generates

• drizzle.config.ts — dialect, schema path, output path, and DB credentials
• src/db/index.ts — provider-specific driver initialisation (postgres, mysql2, better-sqlite3)
• src/db/schema.ts — example 'examples' table definition using Drizzle column helpers

Drivers used per provider

First-run workflow

What the CLI generates

• src/db/data-source.ts — TypeORM DataSource with provider-appropriate driver and entity path
• src/db/entities/Example.ts — @Entity decorated class with @PrimaryGeneratedColumn, @Column
• src/db/index.ts — initializeDatabase() function that initialises the DataSource
• tsconfig.json — experimentalDecorators: true, emitDecoratorMetadata: true added automatically

reflect-metadata

TypeORM requires reflect-metadata. The CLI adds it to dependencies and imports it at the top of src/app.ts — import 'reflect-metadata' must appear before any TypeORM imports.

First-run workflow

Dockerfile

Multi-stage build: a 'builder' stage installs dependencies and compiles TypeScript, then a lean 'production' stage copies only the compiled output and production node_modules. This keeps the final image small.

# Stage 1 — build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2 — production image
FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
CMD ["node", "dist/server.js"]

docker-compose.yml

Defines two services: your Express app (built from the Dockerfile) and the database. The DB service image and port are auto-selected based on your provider choice.

eslint.config.mjs

Uses typescript-eslint's tseslint.config() helper to compose the eslint recommended + typescript-eslint recommended rule sets. Unused variables prefixed with _ are ignored to allow intentional placeholders.

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    rules: {
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },
  { ignores: ['dist/', 'node_modules/', 'coverage/', 'jest.config.js'] }
);

Husky pre-commit hook

lint-staged is configured in package.json and runs on every commit. It lints and formats only the staged .ts files — keeping commits fast by avoiding a full project scan.

// package.json — lint-staged config
"lint-staged": {
  "*.ts": ["eslint --fix", "prettier --write"]
}

jest.config.js

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/tests/**/*.test.ts'],
  moduleNameMapper: {
    // map .js extensions back to .ts source files for ts-jest
    '^(\\.{1,2}/.+)\\.js$': '$1',
  },
};

Generated test files

Useful development commands

git clone https://github.com/vishalvoid/west.js.git && cd west.js

pnpm install

pnpm -F west-js-app test

pnpm -F west-js-app build

node packages/cli/dist/index.js --help

node packages/cli/dist/index.js --yes --name my-test-app --database drizzle --db-provider sqlite

pnpm dev