Express Middleware Patterns

Master authentication, validation, error handling, rate limiting, and logging middleware.

When to Use This Skill

Implementing authentication middleware (JWT, OAuth, sessions)
Creating input validation middleware (Zod, Joi)
Setting up error handling middleware
Adding rate limiting to prevent abuse
Implementing request/response logging
Creating custom middleware for cross-cutting concerns
Handling async errors in route handlers

Authentication Middleware

// middleware/auth.middleware.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';

export interface JWTPayload {
  userId: string;
  email: string;
  roles: string[];
}

declare global {
  namespace Express {
    interface Request {
      user?: JWTPayload;
      token?: string;
    }
  }
}

// Bearer token extraction and verification
export const authenticate = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const authHeader = req.headers.authorization;
    const token = authHeader?.replace('Bearer ', '');

    if (!token) {
      return res.status(401).json({ error: 'No token provided' });
    }

    const payload = jwt.verify(
      token,
      process.env.JWT_SECRET!
    ) as JWTPayload;

    req.user = payload;
    req.token = token;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

// Role-based authorization
export const authorize = (...allowedRoles: string[]) => {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return res.status(401).json({ error: 'Not authenticated' });
    }

    const hasRole = req.user.roles.some(role =>
      allowedRoles.includes(role)
    );

    if (!hasRole) {
      return res.status(403).json({ 
        error: 'Insufficient permissions',
        requiredRoles: allowedRoles,
        userRoles: req.user.roles
      });
    }

    next();
  };
};

// Optional authentication (doesn't fail, just populates req.user if token exists)
export const optionalAuth = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const authHeader = req.headers.authorization;
    const token = authHeader?.replace('Bearer ', '');

    if (token) {
      const payload = jwt.verify(
        token,
        process.env.JWT_SECRET!
      ) as JWTPayload;
      req.user = payload;
    }
  } catch (error) {
    // Silently ignore invalid tokens
  }

  next();
};

// Usage:
// app.get('/protected', authenticate, authorize('admin'), handler);
// app.get('/public', optionalAuth, handler);

Input Validation Middleware

// middleware/validation.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { z, AnyZodObject, ZodError } from 'zod';

// Validation wrapper
export const validate = (schema: AnyZodObject) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      await schema.parseAsync({
        body: req.body,
        query: req.query,
        params: req.params
      });
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        const fieldErrors = error.errors.reduce((acc, err) => {
          const path = err.path.join('.');
          acc[path] = err.message;
          return acc;
        }, {} as Record<string, string>);

        return res.status(400).json({
          error: 'Validation failed',
          fields: fieldErrors
        });
      }
      next(error);
    }
  };
};

// Usage example:
const createUserSchema = z.object({
  body: z.object({
    name: z.string().min(1, 'Name required'),
    email: z.string().email('Invalid email'),
    password: z.string().min(8, 'Password must be 8+ chars'),
    age: z.number().int().positive().optional()
  }),
  query: z.object({
    sendWelcomeEmail: z.enum(['true', 'false']).optional()
  })
});

// app.post('/users', validate(createUserSchema), createUser);

Error Handling Middleware

// utils/errors.ts
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number = 500,
    public isOperational: boolean = true
  ) {
    super(message);
    Object.setPrototypeOf(this, AppError.prototype);
    Error.captureStackTrace(this, this.constructor);
  }
}

export class ValidationError extends AppError {
  constructor(message: string, public fields?: Record<string, string>) {
    super(message, 400);
  }
}

export class NotFoundError extends AppError {
  constructor(message: string = 'Resource not found') {
    super(message, 404);
  }
}

export class UnauthorizedError extends AppError {
  constructor(message: string = 'Unauthorized') {
    super(message, 401);
  }
}

export class ForbiddenError extends AppError {
  constructor(message: string = 'Forbidden') {
    super(message, 403);
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409);
  }
}

// middleware/error-handler.ts
import { Request, Response, NextFunction } from 'express';
import { logger } from './logger.middleware';

export const errorHandler = (
  err: Error | AppError,
  req: Request,
  res: Response,
  next: NextFunction
) => {
  if (err instanceof AppError) {
    logger.warn({
      message: err.message,
      statusCode: err.statusCode,
      path: req.path,
      method: req.method
    });

    return res.status(err.statusCode).json({
      error: err.message,
      ...(err instanceof ValidationError && { fields: err.fields })
    });
  }

  // Unexpected error - log detailed info
  logger.error({
    error: err.message,
    stack: err.stack,
    path: req.path,
    method: req.method,
    body: req.body
  });

  // Don't expose error details in production
  const message = process.env.NODE_ENV === 'production'
    ? 'Internal server error'
    : err.message;

  res.status(500).json({ error: message });
};

// Async error wrapper
export const asyncHandler = (
  fn: (req: Request, res: Response, next: NextFunction) => Promise<any>
) => {
  return (req: Request, res: Response, next: NextFunction) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
};

// Usage:
// app.post('/users', asyncHandler(createUser));
// app.use(errorHandler); // Last middleware

Rate Limiting Middleware

// middleware/rate-limit.middleware.ts
import rateLimit from 'express-rate-limit';
import RedisStore from 'rate-limit-redis';
import Redis from 'ioredis';

const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: parseInt(process.env.REDIS_PORT || '6379')
});

// General API rate limiter
export const apiLimiter = rateLimit({
  store: new RedisStore({
    client: redis,
    prefix: 'rl:api:'
  }),
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,                  // 100 requests per window
  message: 'Too many requests, please try again later',
  standardHeaders: true,     // Return rate limit in headers
  legacyHeaders: false,
  skipSuccessfulRequests: false,
  skipFailedRequests: false,
  keyGenerator: (req) => req.user?.userId || req.ip // Use userId if authenticated
});

// Stricter limit for authentication endpoints
export const authLimiter = rateLimit({
  store: new RedisStore({
    client: redis,
    prefix: 'rl:auth:'
  }),
  windowMs: 15 * 60 * 1000,
  max: 5,                    // Only 5 attempts
  skipSuccessfulRequests: true, // Don't count successful requests
  message: 'Too many login attempts, please try again later'
});

// Usage:
// app.use(apiLimiter);
// app.post('/login', authLimiter, login);

Request Logging Middleware

// middleware/logger.middleware.ts
import { Request, Response, NextFunction } from 'express';
import pino from 'pino';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  transport: {
    target: 'pino-pretty',
    options: {
      colorize: true,
      singleLine: false,
      translateTime: 'SYS:standard'
    }
  }
});

// Request logging middleware
export const requestLogger = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  const startTime = Date.now();
  const requestId = crypto.randomUUID();

  // Attach to request for use in handlers
  req.requestId = requestId;

  // Log response when finished
  res.on('finish', () => {
    const duration = Date.now() - startTime;

    logger.info({
      requestId,
      method: req.method,
      url: req.originalUrl,
      status: res.statusCode,
      duration: `${duration}ms`,
      userAgent: req.headers['user-agent'],
      userId: req.user?.userId,
      ip: req.ip,
      query: req.query,
      // Don't log sensitive fields
      bodySize: JSON.stringify(req.body).length
    });
  });

  next();
};

export { logger };

// Extend Express Request
declare global {
  namespace Express {
    interface Request {
      requestId?: string;
    }
  }
}

CORS Middleware

// Security: Only allow specific origins
const allowedOrigins = [
  'http://localhost:3000',
  'http://localhost:3001',
  'https://example.com',
  'https://www.example.com'
];

app.use(cors({
  origin: (origin, callback) => {
    // Allow requests with no origin (like mobile apps or Postman)
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  exposedHeaders: ['X-Total-Count', 'X-Page-Number'],
  maxAge: 86400 // 24 hours
}));

Middleware Composition

// Create reusable middleware chains
const publicRoutes = [express.json()];

const protectedRoutes = [
  express.json(),
  authenticate,
  requestLogger
];

const adminRoutes = [
  express.json(),
  authenticate,
  authorize('admin'),
  requestLogger
];

// Usage
app.use('/api/public', publicRoutes);
app.use('/api/protected', protectedRoutes);
app.use('/api/admin', adminRoutes);

Middleware Order (Critical!)

// 1. Security headers first
app.use(helmet());

// 2. CORS before routes
app.use(cors(corsOptions));

// 3. Compression
app.use(compression());

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

// 5. Request logging
app.use(requestLogger);

// 6. Rate limiting (before routes)
app.use(apiLimiter);

// 7. Static files
app.use(express.static('public'));

// 8. Routes
app.use('/api', apiRoutes);

// 9. 404 handler
app.use((req, res) => {
  res.status(404).json({ error: 'Not found' });
});

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

Best Practices

Middleware executes in order - Order matters!
Call next() to continue chain - Forgetting it stops the chain
Error middleware needs 4 params - (err, req, res, next)
Use async handlers wrapper - Prevents unhandled rejections
Log security events - Auth failures, rate limit hits, etc
Use custom errors - Makes error handling consistent
Validate all input - Always validate user input
Never expose secrets - Filter sensitive data from logs
Rate limit early - Apply before expensive operations
Test middleware in isolation - Mock req, res, next

Common Patterns

Pattern	Use Case
`authenticate` → `authorize`	Protected routes
`validate()`	Input validation
`asyncHandler()`	Async error handling
`apiLimiter`	Prevent abuse
`requestLogger`	Observability
`errorHandler`	Centralized error handling

middleware-patterns

Express Middleware Patterns

When to Use This Skill

Authentication Middleware

Input Validation Middleware

Error Handling Middleware

Rate Limiting Middleware

Request Logging Middleware

CORS Middleware

Middleware Composition

Middleware Order (Critical!)

Best Practices

Common Patterns

See Also