express-api

When to Use

• Building or refactoring a REST API with Express.js.
• Setting up middleware chains for authentication, logging, or validation.
• Structuring an Express project for maintainability and testability.
• Adding security headers, rate limiting, or CORS configuration.
• Implementing centralized error handling across routes.

Critical Patterns

• Layered Architecture: Separate routes → controllers → services → repositories. Routes define endpoints, controllers handle HTTP concerns, services contain business logic, repositories handle data access.
• Centralized Error Handling: NEVER scatter try/catch in every route. Use an async wrapper and a single error-handling middleware at the end of the middleware chain.
• Validate at the Edge: Validate ALL incoming data (body, params, query) at the route level using Zod or Joi BEFORE it reaches the controller.
• Security by Default: Always use helmet, configure cors explicitly (never * in production), and apply rate limiting to public endpoints.
• Environment Config: Use a validated config module. NEVER access process.env directly throughout the codebase.
• Consistent Response Shape: Every API response should follow the same envelope: { data, error, meta }.

Project Structure

src/
├── config/
│   └── env.ts              # Validated environment config
├── middleware/
│   ├── errorHandler.ts      # Centralized error handler
│   ├── validate.ts          # Request validation middleware
│   ├── auth.ts              # Authentication middleware
│   └── rateLimiter.ts       # Rate limiting config
├── routes/
│   ├── index.ts             # Route aggregator
│   └── users.routes.ts      # /users route definitions
├── controllers/
│   └── users.controller.ts  # HTTP concern handling
├── services/
│   └── users.service.ts     # Business logic
├── repositories/
│   └── users.repository.ts  # Data access
├── errors/
│   └── AppError.ts          # Custom error classes
├── utils/
│   └── asyncHandler.ts      # Async error wrapper
└── app.ts                   # Express app setup