API Development with Express.js

Quick Guide: Express uses middleware-based request processing. The three non-negotiable patterns: modular routing via

express.Router()

, centralized error handling with 4-argument middleware

(err, req, res, next)

, and correct middleware ordering (security first, error handler last). Express 5 (now stable, default on npm) auto-forwards async errors; Express 4 requires manual

next(err)

or a wrapper.

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering,

import type

, named constants)

(You MUST define error-handling middleware with 4 arguments:

(err, req, res, next)

(You MUST register error handlers AFTER all routes and other middleware)

(You MUST call

next(err)

(You MUST use

express.json()

express.urlencoded()

req.body

</critical_requirements>

Auto-detection: Express.js, express, app.use, app.get, app.post, app.put, app.delete, express.Router, req.params, req.query, req.body, res.json, res.status, middleware, next(), error handler, router.use, express.static, express.json, express.urlencoded

When to use:

• Building REST APIs with composable middleware patterns
• Need modular route organization with

  express.Router()

• Require centralized error handling across all routes
• Building APIs that need body parsing, static files, or cookie handling
• Creating route guards for authentication/authorization

When NOT to use:

• Need auto-generated OpenAPI documentation from schemas
• Building edge/serverless functions where cold start matters
• Need strict end-to-end type safety with schema validation
• GraphQL APIs (use a dedicated GraphQL server)

Key patterns covered:

• Middleware chain with

  app.use()

  and

  next()

• Modular routes with

  express.Router()

• Error handling with 4-argument middleware
• Async error forwarding (Express 4 vs 5)
• Request validation middleware
• Route parameters and query string handling
• Route guards for authentication/authorization
• Middleware ordering (security, CORS, rate limit, parsing, routes, errors)

Detailed Resources:

• examples/core.md - App setup, error handler, async handler, body parsing
• examples/middleware.md - Logging, validation, auth guards, middleware ordering
• examples/routing.md - Modular routes, parameters, response helpers, versioned APIs
• reference.md - Decision frameworks, anti-patterns, production checklist

Philosophy

Middleware-first architecture. Express processes requests through a chain of middleware functions. Each middleware can modify request/response objects, end the response, or call

next()

Express 4 vs 5: Express 5 (stable since 2025, now default on npm) auto-forwards errors from rejected promises in async handlers. Express 4 requires explicit

try/catch

next(err)

Core Patterns

Pattern 1: Application Setup

Register body parsers early, mount route modules, register error handler last. See examples/core.md for full implementation.

const app: Express = express();

// Body parsing
app.use(express.json({ limit: JSON_LIMIT }));
app.use(express.urlencoded({ extended: true }));

// Mount route modules
app.use("/api/users", userRoutes);
app.use("/api/products", productRoutes);

// Error handler MUST be last
app.use(errorHandler);

export { app };

Why good: Body parsers before routes so

req.body

Pattern 2: Modular Routes with express.Router()

One Router per resource, mounted at a path prefix. See examples/routing.md for CRUD examples with parameters.

// src/routes/user-routes.ts
const router = Router();

router.get("/", async (req, res, next) => {
  try {
    const users = await getUsersFromDatabase();
    res.status(HTTP_OK).json({ data: users });
  } catch (error) {
    next(error);
  }
});

export { router as userRoutes };

Why good: Router isolates related routes, named export, explicit error forwarding

Pattern 3: Error Handling Middleware (4 Arguments)

Express identifies error handlers by the 4-argument signature

(err, req, res, next)

// CRITICAL: Must have exactly 4 arguments
const errorHandler = (
  err: AppError,
  req: Request,
  res: Response,
  next: NextFunction,
): void => {
  if (res.headersSent) {
    next(err);
    return;
  }

  const statusCode = err.statusCode || HTTP_INTERNAL_ERROR;
  res.status(statusCode).json({
    error: { message: err.message, code: err.code || "INTERNAL_ERROR" },
  });
};

Why good: 4 arguments for Express to recognize as error handler, checks

headersSent

Common mistake: 3-argument function

(err, req, res)

err

req

Pattern 4: Async Error Handling

Express 5 auto-forwards rejected promises. Express 4 requires explicit forwarding. See examples/core.md for the asyncHandler wrapper.

// Express 5: async errors auto-forwarded
router.get("/:id", async (req, res) => {
  const product = await getProductById(req.params.id);
  res.status(HTTP_OK).json({ data: product });
});

// Express 4: MUST forward manually
router.get("/:id", async (req, res, next) => {
  try {
    const product = await getProductById(req.params.id);
    res.status(HTTP_OK).json({ data: product });
  } catch (error) {
    next(error); // Required in Express 4
  }
});

Why this matters: In Express 4, unhandled async rejections cause the request to hang until timeout. Express 5 fixes this but many projects still run Express 4.

Pattern 5: Request Validation Middleware

Validate

req.body

const validateUserCreate = (
  req: Request,
  res: Response,
  next: NextFunction,
): void => {
  const { name, email } = req.body;
  const errors: string[] = [];

  if (!name || name.length < MIN_NAME_LENGTH) errors.push("Name is required");
  if (!email || !email.includes("@")) errors.push("Valid email is required");

  if (errors.length > 0) {
    res
      .status(HTTP_BAD_REQUEST)
      .json({ error: { message: "Validation failed", details: errors } });
    return;
  }
  next();
};

// Apply: router.post("/", validateUserCreate, createHandler);

Why good: Validation separated from business logic, early return on failure, reusable across routes

Pattern 6: Route Guards (Authentication/Authorization)

Protect routes with middleware that validates access. See examples/middleware.md for full auth guard implementation.

// Extend Request with user data
interface AuthenticatedRequest extends Request {
  user?: { id: string; role: string };
}

const requireAuth = (
  req: AuthenticatedRequest,
  res: Response,
  next: NextFunction,
): void => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) {
    res
      .status(HTTP_UNAUTHORIZED)
      .json({ error: { message: "Authentication required" } });
    return;
  }
  req.user = verifyToken(token);
  next();
};

// Apply to all routes in router: router.use(requireAuth);
// Apply to specific route: router.delete("/:id", requireAuth, requireRole("admin"), handler);

Why good: Auth middleware reusable, role guard configurable, extends Request type for type safety

Pattern 7: Middleware Ordering

Order matters. Security first, error handler last. See examples/middleware.md for complete ordering example.

1. Security headers (helmet)
2. CORS
3. Rate limiting (before body parsing to save resources)
4. Body parsing (express.json, express.urlencoded)
5. Request logging
6. Routes
7. 404 handler (after all routes)
8. Error handler (LAST)

Why this order: Security rejects bad requests early. Rate limiting before parsing saves CPU on abusive requests. Error handler must be last to catch all errors from routes.

Pattern 8: Response Helpers

Standardize API responses with typed helpers. See examples/routing.md for full implementation.

const sendSuccess = <T>(res: Response, data: T, statusCode = HTTP_OK): void => {
  res.status(statusCode).json({ success: true, data });
};

const sendNotFound = (res: Response, resource = "Resource"): void => {
  res
    .status(HTTP_NOT_FOUND)
    .json({ success: false, error: { message: `${resource} not found` } });
};

Why good: Consistent response shape across all routes, typed helpers reduce boilerplate

Express 5 Migration Notes

Express 5 is the default on npm since March 2025. Key changes from Express 4:

next(err)

req.body

{}

undefined

req.query

/*

/*splat

/{*splat}

/:file.:ext?

/:file{.:ext}

urlencoded

extended: true

extended: false

req.host

Removed in Express 5:

req.param()

res.send(body, status)

res.send(status)

res.sendStatus()

res.json(obj, status)

res.redirect(url, status)

res.redirect('back')

req.get('Referrer') || '/'

res.sendfile()

res.sendFile()

app.del()

app.delete()

<red_flags>

RED FLAGS

High Priority:

• Error handler has only 3 arguments - Express treats it as regular middleware, errors silently ignored
• Error handler registered before routes - Never catches route errors
• Missing

  next(error)

  in async handlers (Express 4) - Unhandled promise rejection, request hangs
• Not using

  express.json()

  middleware -

  req.body

  is undefined for JSON requests
• Magic HTTP status codes - Use named constants (

  HTTP_OK = 200

  ,

  HTTP_NOT_FOUND = 404

  )

Medium Priority:

• All routes in single file - Creates unmaintainable God file, use

  express.Router()

• Not checking

  res.headersSent

  in error handler - Causes "headers already sent" crashes
• Default exports on route modules - Violates project conventions
• Wildcard CORS with credentials - Browsers reject

  origin: "*"

  with

  credentials: true

• Missing rate limiting on public APIs - Vulnerable to abuse

Gotchas & Edge Cases:

• next('route')

  vs

  next(error)

  - String

  'route'

  skips to next route handler; anything else triggers error handler

• req.query

  values are always strings - Parse numbers with

  parseInt(val, 10)

• express.static

  without auth - Files publicly accessible unless middleware guards them
• Router

  mergeParams: true

  - Required to access parent route params in nested routers
• Express 5:

  req.body

  is

  undefined

  when unparsed - was

  {}

  in Express 4, may break

  if (!req.body)

  checks

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

Before implementing ANY Express route, verify these requirements are met:

All code must follow project conventions in CLAUDE.md

(You MUST define error-handling middleware with 4 arguments:

(err, req, res, next)

(You MUST register error handlers AFTER all routes and other middleware)

(You MUST call

next(err)

(You MUST use

express.json()

express.urlencoded()

req.body

Failure to follow these rules will cause unhandled errors and broken middleware chains.

</critical_reminders>