CLAUDE.md for Express.js: 13 Rules That Stop AI from Breaking Your Middleware Chain

## Stack
- Express: 4.19.2 (NOT 5.x — async error propagation differs)
- Node: 20.12 LTS
- TypeScript: 5.4 (strict mode enabled)

## Async Routes (Express 4)
All async route handlers MUST use the asyncHandler wrapper or explicit try/catch.
Express 4 does NOT catch unhandled Promise rejections in routes.

// CORRECT
router.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await getUser(req.params.id);
  res.json(user);
}));

// WRONG — unhandled rejection in Express 4
router.get('/users/:id', async (req, res) => {
  const user = await getUser(req.params.id); // throws → silent crash
  res.json(user);
});

## Error Handlers
Error-handling middleware MUST have exactly 4 parameters: (err, req, res, next).
Express detects error middleware by arity. 3-param functions are NOT called on error.

// CORRECT
app.use((err, req, res, next) => {
  res.status(err.status || 500).json({ error: err.message });
});

// WRONG — Express treats this as regular middleware
app.use((err, res, next) => { ... }); // 3 params = not an error handler

## Middleware Contract
After calling next(), do NOT read from or write to req or res.
The request may have moved to another middleware or already sent a response.

// CORRECT
function logRequest(req, res, next) {
  const start = Date.now();
  next();
  // do NOT access req.body or res.statusCode here
}

// WRONG
function addHeader(req, res, next) {
  next();
  res.setHeader('X-Custom', 'value'); // may throw if response already sent
}

## Input Validation
ALL route handlers MUST validate request input using zod before any business logic.
Do not use manual checks (if (!req.body.email)) — use schema validation.

import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

router.post('/users', asyncHandler(async (req, res) => {
  const body = CreateUserSchema.parse(req.body); // throws ZodError on invalid input
  // body is now fully typed and validated
}));

## Router Architecture
Feature-specific middleware goes on the feature router, NOT on app.
app.use() middleware applies to ALL routes — use it only for truly global concerns
(body parsing, security headers, request logging).

// CORRECT
const usersRouter = express.Router();
usersRouter.use(requireAuth); // auth only for /users routes
app.use('/users', usersRouter);

// WRONG
app.use(requireAuth); // now applies to /health, /webhooks, everything

## Body Parsing
Routes that need raw body (webhooks, Stripe, GitHub) MUST NOT have express.json()
applied to them. Use express.raw() on those specific routes only.

// CORRECT — raw body for webhook signature verification
app.use('/webhooks/stripe', express.raw({ type: 'application/json' }));
app.use(express.json()); // JSON for everything else

// WRONG — express.json() parses body before signature verification can run
app.use(express.json());
app.post('/webhooks/stripe', stripeHandler); // body already parsed, signature fails

## Error Response Shape
ALL error responses MUST use this exact shape:
{
  "error": {
    "message": "Human-readable description",
    "code": "MACHINE_READABLE_CODE",
    "status": 400
  }
}

Do NOT return { error: "string" }, { message: "string" }, or any other shape.
Validation errors return status 422, not 400.

## Error Handler — Production Safety
The global error handler MUST check NODE_ENV before including stack traces.

app.use((err, req, res, next) => {
  const status = err.status || 500;
  const body = {
    error: {
      message: err.message || 'Internal Server Error',
      code: err.code || 'INTERNAL_ERROR',
      status,
    },
  };
  if (process.env.NODE_ENV !== 'production') {
    body.error.stack = err.stack;
  }
  res.status(status).json(body);
});

## Module Pattern
Route files MUST export an express.Router() instance.
Route files must NOT call app.use() or import the app instance.

// routes/users.ts — CORRECT
const router = express.Router();
router.get('/', getUsers);
export default router;

// app.ts mounts it
app.use('/users', usersRouter);

// WRONG — circular deps, testing nightmare
import app from '../app';
app.use('/users', ...);

## Security Headers
ALL Express apps MUST use helmet() as the first middleware.
Do NOT configure individual security headers manually — use helmet's defaults.

import helmet from 'helmet';
app.use(helmet()); // first middleware, before body parsers

If a header needs customization, configure it through helmet's options,
not by calling res.setHeader() manually.

## Testing Middleware
Middleware functions MUST be unit-testable without starting an HTTP server.
Use node-mocks-http or manual mock req/res objects for middleware tests.
Integration tests (supertest) are for route testing, not middleware testing.

// middleware test — CORRECT
import { mockRequest, mockResponse } from 'node-mocks-http';
import { requireAuth } from './auth-middleware';

test('rejects unauthenticated request', () => {
  const req = mockRequest({ headers: {} });
  const res = mockResponse();
  const next = jest.fn();
  requireAuth(req, res, next);
  expect(res.statusCode).toBe(401);
  expect(next).not.toHaveBeenCalled();
});

## Configuration
App configuration MUST be loaded from environment variables and validated at startup.
Use a config module that throws on missing required variables — do NOT use
process.env.VARIABLE_NAME scattered throughout route handlers.

// config.ts
import { z } from 'zod';

const ConfigSchema = z.object({
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  JWT_SECRET: z.string().min(32),
  NODE_ENV: z.enum(['development', 'test', 'production']),
});

export const config = ConfigSchema.parse(process.env);
// Throws at startup if any required var is missing