express

Express.js HTTP APIs AI Skill Guide (Claude)

Overview & Engine Architecture

Express is a minimal Node HTTP framework of middleware chains and routers. Requests flow top-to-bottom; handlers must end the cycle or call next(). Express 5 forwards rejected promises from async handlers to error middleware automatically; Express 4 needs an async wrapper or explicit .catch(next). Agents validate input (zod/joi), mount 4-arg error middleware last, set trust proxy to hop count—not true, and keep persistence in @prisma / @postgresql with workers for slow jobs (@redis queues).

┌─────────────────────────────────────────────────────────────┐
│                 Express middleware pipeline                   │
│                                                             │
│  Client → reverse proxy / LB (@nginx)                       │
│       → Node process (PM2 / systemd / container)            │
│       → helmet / cors / logger                              │
│       → express.json({ limit })                             │
│       → auth / rate-limit (uses req.ip ← trust proxy)       │
│       → Router("/api/…") → async handler                    │
│            ├── validate (zod) → service → @prisma           │
│            └── next(err) → error middleware → JSON          │
│                                                             │
│  Side paths: BullMQ/worker processes → @redis               │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when

• Building REST/JSON APIs on Node with routers and middleware.
• Fixing hanging requests, misplaced error handlers, or spoofable req.ip.
• Wiring validation + Prisma/Postgres behind Express.

Do not use when

• The surface is GraphQL-first with its own server stack → @graphql-apis (may still mount on Express).
• You only need runtime/process hygiene with no HTTP framework → @nodejs.
• Someone asks to set trust proxy to true without a stripping edge proxy → refuse; use hop count / subnet.