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