/api-framework-express

name: api-framework-express
description: Express.js routes, middleware, error handling, request/response patterns

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)` - Express identifies error handlers by arity)**

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

**(You MUST call `next(err)` to forward async errors in Express 4 - Express 5 auto-forwards rejected promises)**

**(You MUST use `express.json()` and `express.urlencoded()` for body parsing - `req.body` is undefined without them)**

</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](examples/core.md) - App setup, error handler, async handler, body parsing
• [examples/middleware.md](examples/middleware.md) - Logging, validation, auth guards, middleware ordering
• [examples/routing.md](examples/routing.md) - Modular routes, parameters, response helpers, versioned APIs
• [reference.md](reference.md) - Decision frameworks, anti-patterns, production checklist

---

<philosophy>

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()` to continue the chain. Everything in Express is middleware - body parsers, auth guards, loggers, error handlers.

**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)` or a wrapper utility. Both versions require the 4-argument signature for error handlers.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Application Setup

Register body parsers early, mount route modules, register error handler last. See [examples/core.md](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` is populated, error handler last to catch all errors, modular route mounting

---

Pattern 2: Modular Routes with express.Router()

One Router per resource, mounted at a path prefix. See [examples/routing.md](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)`. This is the most critical Express pattern to get right. See [examples/core.md](examples/core.md) for full implementation.

// 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` to avoid double-response, consistent error shape

**Common mistake:** 3-argument function `(err, req, res)` is treated as regular middleware - `err` becomes `req`, completely wrong behavior

---

Pattern 4: Async Error Handling

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

// Express 5: async errors aut