express

Build Express.js routers and middleware with request validation, async error handling, and clear application structure.

SKILL.md

GitHub

Express.js HTTP APIs AI Skill Guide

Overview & Engine Architecture

Express is a minimal Node HTTP framework built around middleware chains and routers. Request flows top-to-bottom; the first matching route wins unless next() continues. Agents keep middleware ordered correctly (parsers before handlers, error middleware last), wrap async routes so rejections reach the error handler, and validate input before business logic.

req -> middleware... -> router -> handler
                              \-> next(err) -> error middleware -> res

When to use this skill

  • Building REST/JSON APIs on Node
  • Splitting apps into domain routers
  • Fixing hanging requests from unhandled async errors
  • Adding auth, logging, and rate-limit middleware

Operational directives

  1. Mount express.json() / urlencoded only where needed; cap body size.
  2. Put four-arg error middleware (err, req, res, next) after all routes.
  3. Wrap async handlers or use a helper so rejected promises call next(err).
  4. Use Router() per domain; keep app.js / server.js thin.
  5. Never trust req.body shape - validate with zod/joi or similar.

App sketch

import express from "express";

const app = express();
app.use(express.json({ limit: "100kb" }));

const items = express.Router();

items.get("/", (_req, res) => {
  res.json([{ id: 1, sku: "A" }]);
});

items.post("/", (req, res, next) => {
  Promise.resolve()
    .then(() => {
      const sku = req.body?.sku;
      if (typeof sku !== "string" || !sku) {
        const err = new Error("sku required");
        err.status = 400;
        throw err;
      }
      res.status(201).json({ id: 2, sku });
    })
    .catch(next);
});

app.use("/items", items);

app.use((err, _req, res, _next) => {
  const status = err.status ?? 500;
  res.status(status).json({ error: err.message ?? "internal error" });
});

app.listen(3000);

Commands

npm install express
node --watch src/server.js
NODE_ENV=production node src/server.js

Common pitfalls

Pitfall Why it hurts Fix
Async throw without next Hanging or crash Async wrapper / catch
Error middleware before routes Never runs Mount last
Giant monolithic app.js Hard to test Domain routers
Trusting proxy headers blindly Spoofed IPs trust proxy + known hops

Best practices

  • Centralize CORS, helmet, and request logging at the edge.
  • Return consistent error JSON shapes for clients.
  • Prefer explicit status codes (201, 204, 409).
  • Test with supertest against the app export (not listen in tests).

Limitations

  • Express 4 vs 5 middleware and path syntax differ - match package major.
  • WebSockets need ws or Socket.IO alongside Express.
  • TypeScript types (@types/express) must align with the Express major version.

Related skills

  • @nodejs - runtime, ESM, process hygiene
  • @graphql-apis - GraphQL layers often mounted on Express
  • @prisma - persistence behind route handlers