---

name: building-express-apis description: Builds production Express.js APIs with TypeScript, middleware patterns, authentication, and error handling. Use when creating Node.js backends, REST APIs, or Express applications.

Express.js

Quick Start

Copyimport express from 'express';
import cors from 'cors';
import helmet from 'helmet';

const app = express();

app.use(helmet());
app.use(cors());
app.use(express.json());

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok' });
});

app.listen(3000);

Features

Common Patterns

Controller Pattern

Copy// controllers/users.ts
import { Request, Response, NextFunction } from 'express';
import { UserService } from '../services/UserService';

export class UserController {
  constructor(private userService: UserService) {}

  getAll = async (req: Request, res: Response, next: NextFunction) => {
    try {
      const users = await this.userService.findAll();
      res.json(users);
    } catch (error) {
      next(error);
    }
  };

  getById = async (req: Request, res: Response, next: NextFunction) => {
    try {
      const user = await this.userService.findById(req.params.id);
      if (!user) return res.status(404).json({ error: 'Not found' });
      res.json(user);
    } catch (error) {
      next(error);
    }
  };
}

Error Handler

Copy// middleware/errorHandler.ts
import { Request, Response, NextFunction } from 'express';

export class AppError extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public isOperational = true
  ) {
    super(message);
  }
}

export function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
) {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({ error: err.message });
  }

  console.error(err);
  res.status(500).json({ error: 'Internal server error' });
}

Validation Middleware

Copy// middleware/validate.ts
import { Request, Response, NextFunction } from 'express';
import { ZodSchema } from 'zod';

export function validate(schema: ZodSchema) {
  return (req: Request, res: Response, next: NextFunction) => {
    const result = schema.safeParse({
      body: req.body,
      query: req.query,
      params: req.params,
    });

    if (!result.success) {
      return res.status(400).json({ errors: result.error.issues });
    }

    next();
  };
}

Workflows

API Development Workflow

1. Define routes in routes/index.ts
2. Create controller with business logic
3. Add validation schemas with Zod
4. Write tests with supertest
5. Document with OpenAPI/Swagger

Middleware Order

Copy1. Security (helmet, cors)
2. Rate limiting
3. Body parsing
4. Logging
5. Authentication
6. Routes
7. 404 handler
8. Error handler

Best Practices

Project Structure

Copysrc/
├── app.ts              # Express setup
├── server.ts           # Server entry
├── config/             # Environment config
├── controllers/        # Route handlers
├── middleware/         # Custom middleware
├── routes/             # Route definitions
├── services/           # Business logic
├── utils/              # Helpers
└── types/              # TypeScript types

For detailed examples and patterns, see reference files above.