Express Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: express for comprehensive documentation.

Basic Setup

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

const app = express();

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

// Routes
app.use('/api/users', userRoutes);

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

app.listen(3000);

Route Patterns

import { Router } from 'express';

const router = Router();

router.get('/', async (req, res, next) => {
  try {
    const users = await db.users.findMany();
    res.json(users);
  } catch (err) {
    next(err);
  }
});

router.post('/', async (req, res, next) => {
  try {
    const user = await db.users.create(req.body);
    res.status(201).json(user);
  } catch (err) {
    next(err);
  }
});

router.get('/:id', async (req, res, next) => {
  const user = await db.users.find(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not found' });
  res.json(user);
});

Middleware Pattern

// Auth middleware
const authenticate = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  if (!token) return res.status(401).json({ error: 'Unauthorized' });

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

router.get('/protected', authenticate, handler);

Error Handler

const errorHandler = (err, req, res, next) => {
  console.error(err.stack);
  res.status(err.status || 500).json({
    error: err.message || 'Internal Server Error'
  });
};

Production Readiness

Security Configuration

import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import rateLimit from 'express-rate-limit';
import slowDown from 'express-slow-down';
import hpp from 'hpp';

const app = express();

// Security headers
app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
    },
  },
  hsts: { maxAge: 31536000, includeSubDomains: true },
}));

// CORS
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
}));

// Rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 100,                   // 100 requests per window
  standardHeaders: true,
  legacyHeaders: false,
  message: { error: 'Too many requests' },
});
app.use('/api', limiter);

// Slow down repeated requests
const speedLimiter = slowDown({
  windowMs: 15 * 60 * 1000,
  delayAfter: 50,
  delayMs: (hits) => hits * 100,
});
app.use('/api', speedLimiter);

// Prevent HTTP Parameter Pollution
app.use(hpp());

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

// Trust proxy (for rate limiting behind reverse proxy)
app.set('trust proxy', 1);

Health Checks

// Health endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

// Readiness endpoint (check dependencies)
app.get('/ready', async (req, res) => {
  try {
    await db.query('SELECT 1');
    res.json({ status: 'ready', database: 'connected' });
  } catch (error) {
    res.status(503).json({ status: 'not ready', database: 'disconnected' });
  }
});

// Liveness endpoint
app.get('/live', (req, res) => {
  res.status(200).send('OK');
});

Structured Logging

import pino from 'pino-http';

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  redact: ['req.headers.authorization', 'req.body.password'],
  serializers: {
    req: (req) => ({
      method: req.method,
      url: req.url,
      query: req.query,
      params: req.params,
    }),
  },
});

app.use(logger);

Monitoring Metrics

Metric	Alert Threshold
Request latency p99	> 500ms
Error rate (5xx)	> 1%
Memory usage	> 80%
Event loop lag	> 100ms
Active handles	> 1000

Graceful Shutdown

const server = app.listen(PORT);

const gracefulShutdown = async (signal: string) => {
  console.log(`${signal} received, shutting down gracefully`);

  server.close(async () => {
    console.log('HTTP server closed');
    await db.disconnect();
    process.exit(0);
  });

  // Force shutdown after 30s
  setTimeout(() => {
    console.error('Forced shutdown');
    process.exit(1);
  }, 30000);
};

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT', () => gracefulShutdown('SIGINT'));

Error Handler (Production)

const errorHandler = (err, req, res, next) => {
  // Log error
  req.log.error({
    err,
    method: req.method,
    url: req.url,
    body: req.body,
  });

  // Don't leak error details in production
  const statusCode = err.statusCode || err.status || 500;
  const message = statusCode === 500 && process.env.NODE_ENV === 'production'
    ? 'Internal Server Error'
    : err.message;

  res.status(statusCode).json({
    error: message,
    ...(process.env.NODE_ENV !== 'production' && { stack: err.stack }),
  });
};

// Must be last middleware
app.use(errorHandler);

Checklist

• Helmet security headers enabled
• CORS properly configured
• Rate limiting on API endpoints
• Body size limits configured
• Input validation (express-validator/joi)
• HPP protection enabled
• Structured logging (no console.log)
• Health/readiness/liveness endpoints
• Graceful shutdown handling
• Error details hidden in production
• HTTPS/TLS in production
• Trust proxy configured (if behind LB)

When NOT to Use This Skill

• Enterprise Architecture: Use NestJS for dependency injection, decorators, and modular design
• Maximum Performance: Use Fastify for schema-based validation and faster throughput
• Edge Runtimes: Use Hono for Cloudflare Workers, Vercel Edge, or edge-first design
• Type-Safe APIs: Consider tRPC with Express or use Fastify/NestJS for better TypeScript integration
• WebSocket Implementation: Use dedicated WebSocket skill (coming soon)
• GraphQL: Defer to graphql-expert for Apollo Server setup
• Database Queries: Use prisma-expert or sql-expert for ORM/query specifics

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Using app.get('*') before specific routes	Catches all requests, routes unreachable	Place catch-all routes last
Not using next() in middleware	Request hangs, no response sent	Always call next() or send response
Synchronous error throwing without try-catch	Crashes server	Wrap in try-catch, use next(err)
Using res.send() multiple times	"Headers already sent" error	Send response once per request
Not setting trust proxy behind load balancer	Wrong client IP, rate limiting fails	Set app.set('trust proxy', 1)
Parsing body without size limits	DoS vulnerability	Set limit: '10kb' in body parsers
Using app.use(express.static()) without path	Serves entire filesystem	Specify explicit public directory
Mixing callback and promise styles	Inconsistent error handling	Use async/await consistently

Quick Troubleshooting

Issue	Likely Cause	Solution
"Cannot set headers after sent"	Multiple res.send() calls	Ensure only one response per request
Middleware not executing	Registered after routes	Move app.use() before route definitions
404 for all routes	Routes defined after app.listen()	Define routes before calling listen()
Request hangs indefinitely	Middleware missing next()	Add next() or send response
CORS errors despite cors middleware	Middleware order issue	Place app.use(cors()) before routes
Rate limiting not working	Behind proxy without trust proxy	Set app.set('trust proxy', 1)
Body parser returns undefined	Wrong content-type header	Ensure Content-Type: application/json
Static files not serving	Wrong path configuration	Use absolute path: express.static(path.join(__dirname, 'public'))

WebSocket Integration

Note: For WebSocket functionality, consider using a dedicated WebSocket library alongside Express.

Setup with ws

import express from 'express';
import { createServer } from 'http';
import { WebSocketServer, WebSocket } from 'ws';

const app = express();
const server = createServer(app);
const wss = new WebSocketServer({ server });

// Connection handling
wss.on('connection', (ws: WebSocket, req) => {
  const userId = new URL(req.url!, `http://${req.headers.host}`).searchParams.get('userId');
  console.log(`Client connected: ${userId}`);

  ws.on('message', (data) => {
    const message = JSON.parse(data.toString());
    handleMessage(ws, message);
  });

  ws.on('close', () => {
    console.log(`Client disconnected: ${userId}`);
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });
});

server.listen(3000);

Authentication

import { WebSocketServer } from 'ws';
import jwt from 'jsonwebtoken';

const wss = new WebSocketServer({
  server,
  verifyClient: async ({ req }, done) => {
    const token = req.url?.split('token=')[1];
    if (!token) return done(false, 401, 'Unauthorized');

    try {
      const decoded = jwt.verify(token, process.env.JWT_SECRET!);
      (req as any).user = decoded;
      done(true);
    } catch {
      done(false, 401, 'Invalid token');
    }
  },
});

Room Management

const rooms = new Map<string, Set<WebSocket>>();

function joinRoom(ws: WebSocket, roomId: string) {
  if (!rooms.has(roomId)) {
    rooms.set(roomId, new Set());
  }
  rooms.get(roomId)!.add(ws);
}

function leaveRoom(ws: WebSocket, roomId: string) {
  rooms.get(roomId)?.delete(ws);
  if (rooms.get(roomId)?.size === 0) {
    rooms.delete(roomId);
  }
}

function broadcastToRoom(roomId: string, message: object, exclude?: WebSocket) {
  const clients = rooms.get(roomId);
  if (!clients) return;

  const data = JSON.stringify(message);
  clients.forEach((client) => {
    if (client !== exclude && client.readyState === WebSocket.OPEN) {
      client.send(data);
    }
  });
}

Heartbeat & Connection Health

const HEARTBEAT_INTERVAL = 30000;

wss.on('connection', (ws: WebSocket) => {
  (ws as any).isAlive = true;

  ws.on('pong', () => {
    (ws as any).isAlive = true;
  });
});

const heartbeat = setInterval(() => {
  wss.clients.forEach((ws) => {
    if ((ws as any).isAlive === false) {
      return ws.terminate();
    }
    (ws as any).isAlive = false;
    ws.ping();
  });
}, HEARTBEAT_INTERVAL);

wss.on('close', () => clearInterval(heartbeat));

Message Protocol

interface WSMessage {
  type: string;
  payload: unknown;
  timestamp: number;
}

function handleMessage(ws: WebSocket, message: WSMessage) {
  switch (message.type) {
    case 'join_room':
      joinRoom(ws, message.payload as string);
      break;
    case 'leave_room':
      leaveRoom(ws, message.payload as string);
      break;
    case 'broadcast':
      broadcastToRoom(
        (message.payload as any).roomId,
        (message.payload as any).data
      );
      break;
    default:
      ws.send(JSON.stringify({ type: 'error', payload: 'Unknown message type' }));
  }
}

Scaling with Redis

import { createClient } from 'redis';

const pub = createClient({ url: process.env.REDIS_URL });
const sub = pub.duplicate();

await pub.connect();
await sub.connect();

// Subscribe to channel
await sub.subscribe('ws:broadcast', (message) => {
  const data = JSON.parse(message);
  wss.clients.forEach((client) => {
    if (client.readyState === WebSocket.OPEN) {
      client.send(JSON.stringify(data));
    }
  });
});

// Publish from any server instance
function publishMessage(channel: string, message: object) {
  pub.publish(channel, JSON.stringify(message));
}

Reference Documentation

• Middleware Patterns
• Error Handling