Express 5 API skill for Codex

Done well means: every route validates its input before touching business logic, every error (sync, async, thrown or rejected) reaches one error handler that returns a consistent JSON body, the app object is importable without opening a port so tests run in-process, and the server drains connections on SIGTERM.

Inspect before changing anything

• Read AGENTS.md and package.json: Express major version, module type ("type": "module" or CommonJS), TypeScript setup, test runner, Node version (Express 5 needs Node 18+).
• npm ls express (or pnpm/yarn equivalent) to confirm the installed version; v4 and v5 differ in routing syntax and error handling.
• Find the middleware chain: rg -n "app\.use\(|router\.use\(" src.
• Find the existing error handler: rg -n "\(err, req, res, next\)|ErrorRequestHandler" src.
• If the project is on Express 4 and the task is an upgrade, read references/express-5-migration.md before editing.

Layout

src/
  app.ts              # builds and exports the app, no listen()
  server.ts           # listen(), shutdown signals
  config.ts           # env parsing (validated once at boot)
  middleware/         # auth, requestId, validate, errorHandler
  modules/
    orders/
      orders.router.ts
      orders.schemas.ts
      orders.service.ts   # no req/res here: plain inputs, plain outputs
      orders.test.ts

Keep req/res out of services so they can be called from jobs, scripts and tests.

Middleware order

// app.ts
import express from "express";
import helmet from "helmet";
import cors from "cors";
import pinoHttp from "pino-http";

export function createApp(deps: Deps) {
  const app = express();
  app.disable("x-powered-by");
  app.set("trust proxy", 1);                 // exactly the number of proxies in front
  app.use(pinoHttp({ genReqId: (req) => req.headers["x-request-id"] ?? crypto.randomUUID() }));
  app.use(helmet());
  app.use(cors({ origin: deps.config.corsOrigins, credentials: true }));
  app.use(express.json({ limit: "100kb" }));

  app.get("/healthz", (_req, res) => { res.json({ ok: true }); });
  app.use("/v1/orders", ordersRouter(deps));

  app.use(notFound);                          // after all routes
  app.use(errorHandler);                      // last, 4 arguments
  return app;
}

Concern	Placement rule
Request id / logging	First, so every later log line carries the id
Security headers, CORS	Before routes; CORS before auth so preflights succeed
Body parsers	Global with a size limit, or per-route for webhooks needing the raw body
Rate limiting	Before expensive work; keyed per user or API key, not only per IP
Auth	Per router, so health checks and public routes stay open
404 + error handler	Last

trust proxy set to true lets any client spoof X-Forwarded-For, which breaks IP-based rate limits. Use the hop count or the proxy’s subnet.

Async errors

Express 5 forwards rejected promises from handlers and middleware to the error handler, so express-async-errors and manual try/catch + next(err) wrappers are unnecessary. Remove them during upgrades. Errors thrown inside callbacks that Express does not await (timers, event emitters, un-awaited promises) still escape: await everything.

// errors.ts
export class AppError extends Error {
  constructor(public status: number, public code: string, message: string, public details?: unknown) {
    super(message);
  }
}

// middleware/errorHandler.ts
import type { ErrorRequestHandler } from "express";
export const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
  if (res.headersSent) return next(err);       // let Express close the connection
  if (err instanceof AppError) {
    return res.status(err.status).json({ error: { code: err.code, message: err.message, details: err.details } });
  }
  if (err?.type === "entity.parse.failed") {
    return res.status(400).json({ error: { code: "invalid_json", message: "Malformed JSON body" } });
  }
  if (err?.type === "entity.too.large") {
    return res.status(413).json({ error: { code: "payload_too_large", message: "Body too large" } });
  }
  req.log.error({ err }, "unhandled error");
  res.status(500).json({ error: { code: "internal", message: "Internal server error" } });
};

Never send err.message or stack traces for unknown errors to clients. If the project standardises on RFC 9457 problem details, follow $problem-details-errors for the shape.

Validation

Validate params, query and body at the edge with Zod (or the project’s existing library). In Express 5, req.query is a getter and cannot be reassigned, so put parsed values somewhere else:

import type { RequestHandler } from "express";
import { z, type ZodType } from "zod";

export const validate = <B, Q, P>(s: { body?: ZodType<B>; query?: ZodType<Q>; params?: ZodType<P> }): RequestHandler =>
  (req, res, next) => {
    const out: Record<string, unknown> = {};
    for (const key of ["body", "query", "params"] as const) {
      const schema = s[key];
      if (!schema) continue;
      const r = schema.safeParse(req[key]);
      if (!r.success) throw new AppError(422, "validation_failed", `Invalid ${key}`, r.error.issues);
      out[key] = r.data;
    }
    res.locals.input = out;
    next();
  };

router.post("/", validate({ body: CreateOrder }), async (req, res) => {
  const order = await deps.orders.create(req.user.id, res.locals.input.body);
  res.status(201).location(`/v1/orders/${order.id}`).json(order);
});

express.json() leaves req.body as undefined (not {}) when no body was parsed in Express 5; schemas must handle that.

Routing rules (Express 5 / path-to-regexp v8)

Express 4	Express 5
app.get("*", ...)	app.get("/*splat", ...) (wildcards must be named)
"/files/*"	"/files/*path"; req.params.path is an array of segments
"/:file.:ext?"	"/:file{.:ext}" (braces mark optional parts)
Regex characters in string paths ("/user/:id(\\d+)")	Not supported: validate id in the handler or schema

Mount routers with app.use(prefix, router) and use express.Router({ mergeParams: true }) when a child router needs parent params.

Graceful shutdown

// server.ts
const server = app.listen(config.port, () => logger.info({ port: config.port }, "listening"));
server.keepAliveTimeout = 65_000;   // above the load balancer idle timeout (ALB default 60 s)
server.headersTimeout = 66_000;     // must exceed keepAliveTimeout

for (const sig of ["SIGTERM", "SIGINT"] as const) {
  process.once(sig, () => {
    logger.info({ sig }, "draining");
    server.close(() => { void deps.db.end().then(() => process.exit(0)); });
    server.closeIdleConnections();
    setTimeout(() => process.exit(1), 10_000).unref();
  });
}

Testing

import request from "supertest";
const app = createApp(testDeps());

it("rejects an invalid order with 422", async () => {
  const res = await request(app).post("/v1/orders").set("Authorization", `Bearer ${token}`).send({ qty: -1 });
  expect(res.status).toBe(422);
  expect(res.body.error.code).toBe("validation_failed");
});

Cover per route: happy path, validation failure, unauthenticated, forbidden (other user’s resource), not found, and one case where the service throws (500 body hides internals).

Gotchas

• Middleware that neither responds nor calls next() hangs the request until the client times out. Every branch must do one or the other.
• res.json() after a response was sent throws ERR_HTTP_HEADERS_SENT; return after responding.
• A raw-body webhook route must be registered before the global express.json(), or use express.raw({ type: "application/json" }) on that route only.
• app.listen() inside app.ts makes tests open real ports and leak handles.
• res.status() in Express 5 throws on invalid codes (non-integers, out of 100-999); do not pass through upstream status values unchecked.
• cors({ origin: "*", credentials: true }) is rejected by browsers; list origins.

Verification

npx tsc --noEmit            # if TypeScript
npm test                    # or the command from AGENTS.md

Then start the server and check one route of each kind with curl, including a malformed JSON body (expect 400 JSON, not an HTML stack page) and an unknown path (expect the JSON 404). If anything returns HTML, the error handler is missing or registered too early.

Output template

## Express change: <summary>
- Routes: <method path -> status codes>
- Validation: <schemas added>
- Middleware order changes: <if any>
- Error codes introduced: <code: status>
- Tests: <file: cases>
- Follow-ups: <e.g. rate limit store, OpenAPI update>