How to implement automatic WebSocket reconnection
exponential backoff, jitter, max retry limit, reconnect on close code, storing pending messages, reconnect state flag, clearTimeout cleanup
WebSockets Drop — Your Client Must Recover
Network drops, server restarts, and idle timeouts all close WebSocket connections. A production client must reconnect automatically. Naive immediate reconnect hammers the server. Use exponential backoff:
let retryCount = 0; let retryTimeout = null; function connect() { const ws = new WebSocket('wss://api.example.com/ws'); ws.onopen = () => { retryCount = 0; // reset on success }; ws.onclose = (event) => { if (event.code === 1000) return; // intentional close const delay = Math.min(1000 * 2 ** retryCount, 30000); const jitter = Math.random() * 1000; retryCount++; retryTimeout = setTimeout(connect, delay + jitter); }; return ws; }
Jitter Is Not Optional
Without jitter, every client that lost connection at the same moment (server restart) reconnects at exactly the same intervals, creating synchronized thundering herds. Adding Math.random() * 1000 spreads reconnect attempts across a one-second window, which reduces load spikes dramatically at scale.
Cap retry delay at 30 seconds. After 5–10 failures, surface a UI message so users know they are offline rather than leaving them staring at a spinner indefinitely. Always cancel pending setTimeout calls when the component unmounts or the user navigates away.