Backend Node + Express Development Skill

Expert guidance for building production-grade, API-only Node.js + Express backends. This skill ensures every new backend project starts with a clean architecture, consistent patterns, and security-first defaults — whether in JavaScript or TypeScript.

---

Instructions

Step 1: Confirm Project Basics

Before writing any code, clarify with the user:

1. Language: JavaScript or TypeScript?
2. Database: PostgreSQL, MySQL, MongoDB, or other?
3. ORM/Query builder: Prisma, Knex, Mongoose, raw driver?
4. Auth strategy: JWT or session-based?

If the user doesn't specify, default to: TypeScript + PostgreSQL + Prisma + JWT.

Node Version: Require Node 24 LTS (Active LTS), preferably >=24.10.0 for non-experimental env-file support. Use node --watch for dev restarts and --env-file-if-exists for env loading — no nodemon or dotenv needed. For the full version/stability table and lifecycle guidance, see node-version-guide.md.

Pin the Node version in .nvmrc — e.g. 24 or a specific 24.x.y (>=24.10.0 recommended).

Step 2: Scaffold the Folder Structure

Always generate this folder structure. Adapt file extensions based on JS vs TS.

.
├─ src/
│  ├─ app/
│  │  ├─ app.(js|ts)                 # Express app: middleware stack + route mounting
│  │  └─ server.(js|ts)              # HTTP server start + graceful shutdown
│  ├─ config/
│  │  ├─ env.(js|ts)                 # Env var parsing + validation (fail fast on boot)
│  │  └─ index.(js|ts)               # Normalized config object (single source of truth)
│  ├─ routes/
│  │  ├─ index.(js|ts)               # Mount all versioned routers (e.g. /api/v1)
│  │  └─ v1/
│  │     ├─ health.routes.(js|ts)    # Health + readiness endpoints
│  │     └─ users.routes.(js|ts)     # Example resource module
│  ├─ controllers/
│  │  └─ users.controller.(js|ts)    # HTTP glue only (thin — no business logic)
│  ├─ services/
│  │  └─ users.service.(js|ts)       # All business logic and use-cases
│  ├─ repositories/
│  │  └─ users.repo.(js|ts)          # DB access only (queries, ORM calls)
│  ├─ db/
│  │  ├─ client.(js|ts)              # DB connection pool / Prisma client
│  │  ├─ migrations/                 # Database migration files
│  │  └─ seed/                       # Seed scripts for dev/test data
│  ├─ middlewares/
│  │  ├─ auth.(js|ts)                # Authentication middleware
│  │  ├─ error-handler.(js|ts)       # Global error handler (MUST be last middleware)
│  │  ├─ rate-limit.(js|ts)          # Rate limiting (global + per-route)
│  │  └─ request-id.(js|ts)          # Adds req.id for log correlation
│  ├─ validators/
│  │  └─ users.schema.(js|ts)        # Zod or Joi schemas for request validation
│  ├─ errors/
│  │  ├─ AppError.(js|ts)            # Custom error base class with status + code
│  │  └─ error-codes.(js|ts)         # Stable, documented error codes map
│  ├─ logging/
│  │  └─ logger.(js|ts)              # Structured logger (pino/winston) + secret redaction
│  ├─ utils/
│  │  ├─ async-handler.(js|ts)       # Wraps async controllers (no try/catch boilerplate)
│  │  └─ http-response.(js|ts)       # Standardized success/error response helpers
│  └─ types/                         # TS only: shared interfaces and type definitions
│
├─ tests/
│  ├─ unit/                          # Service + utility unit tests
│  ├─ integration/                   # Route + DB integration tests
│  └─ e2e/                           # Full flow end-to-end tests
│
├─ docs/
│  ├─ openapi.yaml                   # OpenAPI spec (recommended)
│  └─ runbook.md                     # Deploy, rollback, and ops notes
│
├─ scripts/                          # One-off scripts (backfills, maintenance)
├─ docker/                           # Dockerfile, docker-compose, local infra
├─ .github/workflows/                # CI pipeline config
├─ .env.example                      # Documented env var template
├─ .editorconfig
├─ .nvmrc                            # Pin Node version
├─ .eslintrc.* / eslint.config.*
├─ .prettierrc / prettier.config.*
├─ README.md
└─ package.json

CRITICAL rules:

• One language per repo — never mix JS and TS source files.
• For TS repos, compile to a dist/ folder; never run raw .ts in production.
• Every new feature module replicates the same pattern: routes → controller → service → repository → validator.
• Keep types/ for TS-only shared interfaces; omit for JS repos.

Step 3: Follow the Request Flow

All requests MUST flow through these layers in order:

Route → Controller → Service → Repository

Layer	Responsibility	Rules
Routes	Define URL paths + HTTP methods	Only call controllers. No logic.
Controllers	Parse/validate input, call service, format response	THIN — no business logic, no DB calls
Services	Business logic, permissions, orchestration	May call multiple repos. Owns transactions.
Repositories	Database queries only	Return domain objects, not raw DB rows

NEVER skip layers. Controllers must NOT call repositories directly. Services must NOT write raw SQL.

Step 4: Apply Security Defaults

Every backend MUST include these from day one:

1. Helmet — secure HTTP headers
2. CORS — explicit allowlist (never use * in production)
3. Rate limiting — global + stricter on auth routes (login, register)
4. Body size limits — prevent payload abuse
5. Input validation — validate params, query, and body on every endpoint using Zod or Joi
6. Password hashing — bcrypt or argon2 (NEVER store plaintext passwords)
7. Secret redaction — never log tokens, passwords, or API keys
8. Auth consistency — pick JWT or sessions and stick with one approach

Step 5: Implement the Middleware Stack

Mount middleware in this exact order:

1. request-id — assigns unique ID to every request
2. Logger middleware — logs request start/end with request ID
3. helmet — security headers
4. cors — cross-origin policy
5. Body parsers (express.json(), express.urlencoded()) + size limits
6. Rate limiter
7. Auth middleware — only on protected routes
8. Routes — mount /api/v1/*
9. 404 handler — catch unmatched routes
10. Global error handler — MUST be last

Step 6: Standardize API Responses

Use a consistent response shape across ALL endpoints:

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user found with the given ID.",
    "details": null
  }
}

Use correct HTTP status codes:

• 400 — validation errors
• 401 — unauthenticated
• 403 — forbidden (authenticated but not authorized)
• 404 — resource not found
• 409 — conflict (duplicate, etc.)
• 429 — rate limited
• 500+ — server errors

Step 7: Set Up Error Handling

• Create a custom AppError class extending Error with statusCode, code, and isOperational properties.
• Use an async-handler wrapper for all controller methods to catch rejected promises automatically.
• The global error handler middleware (LAST in the stack) catches everything:
  • Known AppError → return structured error with the appropriate status.
  • Unknown errors → log full stack trace, return generic 500 to client.
  • NEVER leak stack traces or internal details in production responses.
• Define stable error codes in error-codes.(js|ts) — clients depend on these, not message strings.

Step 8: Configure Logging and Observability

• Use a structured JSON logger (pino recommended, winston acceptable).
• Attach req.id (request ID) to every log entry for correlation.
• Include response headers: x-request-id.
• Add health endpoints:
  • GET /api/v1/health — always returns 200 if process is alive.
  • GET /api/v1/ready — checks DB and external service connectivity.
• Redact any secrets, tokens, or passwords from all log output.

Step 9: Configure Environment and Scripts

Environment:

• Validate ALL env vars on boot using the config module — crash immediately if required vars are missing.
• Centralize env access in src/config/index.(js|ts) — NEVER scatter process.env.* across the codebase.
• Provide .env.example documenting every required and optional variable.
• Do NOT install dotenv — use Node's built-in env loading instead.

Package.json scripts depend on your Node version. See scripts-and-env.md for the full 3-tier guide (Tier A: Node >=24.10.0 non-experimental, Tier B: Node 22.9+ experimental flags, Tier C: Node 20.12+ programmatic loading).

Quick reference (Tier A / recommended):

• JS dev: node --watch --env-file-if-exists=.env src/app/server.js
• TS dev: tsc -w in terminal 1, node --watch --env-file-if-exists=.env dist/app/server.js in terminal 2

Always include: lint, format, test, test:watch, migrate, seed

IMPORTANT: Do NOT add nodemon, dotenv, or tsx as dependencies.

Step 10: Database Best Practices

• ALWAYS use migrations — never modify schema by hand in production.
• Use connection pooling with proper timeout configuration.
• Wrap multi-step writes in transactions.
• Index intentionally and monitor slow queries.
• Keep ALL database logic inside repositories/ — services never write raw queries.
• Seed scripts go in src/db/seed/ for reproducible dev/test data.

Step 11: Testing Strategy

• Unit tests (tests/unit/) — test services, utilities, and pure logic in isolation.
• Integration tests (tests/integration/) — test routes with a real DB (use Docker).
• E2E tests (tests/e2e/) — test complete user flows end-to-end.
• Use supertest for HTTP assertions in integration tests.
• Use factories/fixtures for predictable, reproducible test data.
• Testing framework: vitest (preferred) or jest.
• Zero-dependency alternative: Node's built-in test runner (node --test) is stable since Node 20 and supports describe/it and assertions. Module mocking requires --experimental-test-module-mocks; coverage via --experimental-test-coverage. Vitest and Jest remain excellent for richer ecosystems.

Step 12: Production Readiness

Before deploying, ensure:

1. Graceful shutdown — stop accepting requests, drain connections, close DB pool, stop background workers.
2. Docker — multi-stage build, non-root user, healthcheck wired to /api/v1/health.
3. Stateless — no in-memory state; use external stores (Redis, DB) for sessions/cache.
4. 12-Factor — log to stdout/stderr, config via env vars, one codebase per deploy.
5. CI pipeline — lint → test → build (TS) → optional security scan → optional integration tests with Dockerized DB.
6. Secrets — use a secret manager in production; never commit .env files.

Step 13: Naming Conventions

Type	Pattern	Example
Routes	*.routes.(js|ts)	users.routes.ts
Controllers	*.controller.(js|ts)	users.controller.ts
Services	*.service.(js|ts)	users.service.ts
Repositories	*.repo.(js|ts)	users.repo.ts
Validators	*.schema.(js|ts)	users.schema.ts
Errors	AppError.(js|ts)	AppError.ts
Config	Descriptive names	env.ts, index.ts

Step 14: Recommended Dependencies

Runtime:

• express — web framework
• helmet — secure headers
• cors — cross-origin requests
• zod or joi — request validation
• pino or winston — structured logging
• DB driver: pg, mysql2, mongoose, or prisma

NOT needed (handled by Node.js built-ins):

• dotenv — use --env-file-if-exists (non-experimental in Node >=24.10.0) or process.loadEnvFile() (Node >=20.12.0)
• nodemon — use node --watch (stable since Node >=20.13.0)
• tsx — use tsc -w + node --watch (or native TS in Node >=22.18.0)

Dev tooling:

• eslint + prettier — code quality
• vitest or jest — test runner (or node --test for zero-dependency testing; coverage via --experimental-test-coverage)
• supertest — HTTP integration testing
• husky + lint-staged — git hooks (optional but recommended)
• typescript — compiler (TS repos only)

---

Examples

Example 1: New Backend Project

User says: "Create a new Express API for a task management app"

Actions:

1. Confirm: TypeScript, PostgreSQL, Prisma, JWT (or ask user preference)
2. Scaffold the full folder structure with tasks as the first resource module
3. Create routes/v1/tasks.routes.ts, controllers/tasks.controller.ts, services/tasks.service.ts, repositories/tasks.repo.ts, validators/tasks.schema.ts
4. Set up middleware stack in correct order
5. Configure env validation, logger, error handling
6. Add health endpoints
7. Create package.json with node --watch dev script and --env-file-if-exists for env loading — no nodemon or dotenv
8. Provide .env.example
9. Pin 24 in .nvmrc (Node 24 LTS)

Example 2: Adding a New Feature Module

User says: "Add an orders feature to my API"

Actions:

1. Create the full module following the established pattern:
   • routes/v1/orders.routes.(js|ts)
   • controllers/orders.controller.(js|ts)
   • services/orders.service.(js|ts)
   • repositories/orders.repo.(js|ts)
   • validators/orders.schema.(js|ts)
2. Add migration for the orders table
3. Mount routes in routes/v1/ index
4. Follow existing naming and response conventions

Example 3: Backend Code Review

User says: "Review my Express backend structure"

Actions:

1. Check folder structure against the recommended layout
2. Verify the request flow (Route → Controller → Service → Repository)
3. Check for security defaults (helmet, cors, rate limiting, validation)
4. Verify error handling pattern (AppError, global handler, async wrapper)
5. Review middleware ordering
6. Flag any anti-patterns (business logic in controllers, raw SQL in services, scattered env access)

---

Reference Files

• Node version details: See node-version-guide.md for the full version/stability table, lifecycle guidance, watch flags, and native TypeScript details.
• Script tiers and env loading: See scripts-and-env.md for all 3 tiers of package.json scripts based on Node version.
• Troubleshooting: See troubleshooting.md for common anti-patterns and the rationale behind --env-file-if-exists.