express-api

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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
```

## Code Examples

### App Setup with Security Middleware

```typescript
import express from "express";
import helmet from "helmet";
import cors from "cors";
import { rateLimit } from "express-rate-limit";
import { errorHandler } from "./middleware/errorHandler";
import { routes } from "./routes";

const app = express();

// Security middleware — order matters
app.use(helmet());
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(",") ?? [],
  credentials: true,
}));
app.use(rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
}));

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

// Routes
app.use("/api/v1", routes);

// Health check — outside versioned routes
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});

// Centralized error handler — MUST be last
app.use(errorHandler);

export { app };
```

### Async Error Wrapper

```typescript
import { Request, Response, NextFunction, RequestHandler } from "express";

// Wraps async route handlers so thrown errors reach the error middleware
export const asyncHandler = (
  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>
): RequestHandler => {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
};
```

### Custom Error Classes

```typescript
export class AppError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly message: string,
    public readonly isOperational = true,

From dallay/agents-skills, MIT.

More from dallay/agents-skills