Home › Node.js / TypeScript › Express 5 API AGENTS.md

Express 5 API AGENTS.md

AGENTS.md for Express 5 REST APIs in TypeScript with zod validation, error middleware, and supertest.

AGENTS.mdNode.js / TypeScript

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Express 5 API

## Commands
`npm run dev` · `npm test` · `npm run lint` · `npx tsc --noEmit`

## Layout
- `src/app.ts` builds the app (no `listen`), `src/server.ts` starts it. Tests import `app.ts`.
- `src/routes/<resource>.ts` defines an `express.Router()`; handlers call `src/services/*`.

## Rules
- Express 5 forwards rejected promises to error middleware, so use `async` handlers and don't wrap them in try/catch just to call `next(err)`.
- Validate `req.body`, `req.params` and `req.query` with zod schemas at the top of each handler; respond 400 with the flattened issues.
- One error middleware (4 args) at the end maps known errors to status codes and logs the rest. Never leak stack traces in production responses.
- Express 5 path syntax: named wildcards (`/*splat`) and `{optional}` segments; the old `?` and bare `*` patterns don't work.
- Security baseline: `helmet()`, `express.json({ limit: '100kb' })`, CORS with an explicit origin list, rate limiting on auth routes.
- Config from a validated env module; fail fast at startup if something is missing.
- Structured logging (pino) with a request id.

## Don't
- Don't use `body-parser` (built in) or `req.param()` (removed).
- Don't put DB queries directly in route files.

## Done
Typecheck, lint and `supertest` tests for every new route (happy path + validation error) pass.