WebSockets

Real-time bidirectional communication between browser and server — opening connections, sending messages, handling events, and reconnecting.

What it is, in plain English: A WebSocket is a persistent, full-duplex communication channel between a browser and a server. Unlike HTTP (which is request-response), a WebSocket connection stays open — the server can push data to the client at any time without the client asking. This makes WebSockets ideal for chat apps, live dashboards, multiplayer games, collaborative editing, and any application that needs real-time updates.

Where this bites you

new WebSocket(url) returns immediately, but the connection isn't open yet: the handshake still has to happen over the network. Calling send() right away throws InvalidStateError: Still in CONNECTING state. It's an easy mistake when the first message ("join this room") is written straight after the constructor, as in the sending examples above.

const ws = new WebSocket("ws://localhost:8765/ws");
ws.onmessage = (e) => console.log(e.data);

ws.send(JSON.stringify({ type: "join", room: "general" }));   // right after creating it
// InvalidStateError: Failed to execute 'send' on 'WebSocket': Still in CONNECTING state.

Staying connected — real-time data from the server

HTTP works like sending a letter: you send a request, the server replies, done. A WebSocket is like a phone call: the connection stays open, and both sides can talk whenever they want. This is how chat apps, live stock prices, multiplayer games, and collaborative tools work.

Opening a WebSocket connection

// wss:// = secure WebSocket (like https)
// ws://  = insecure (use only in development/localhost)
const ws = new WebSocket("wss://api.example.com/ws");

// Events — what can happen to the connection:
ws.onopen = () => {
  console.log("Connected to server!");
  ws.send("Hello server!");  // send as soon as connected
};

ws.onmessage = (event) => {
  // event.data = the message from the server (string or Blob)
  console.log("Server says:", event.data);
};

ws.onerror = (error) => {
  console.error("Connection error");
};

ws.onclose = (event) => {
  console.log("Disconnected. Code:", event.code);
};

Sending and receiving messages

// Send a plain text message:
ws.send("Hello!");

// Send JSON (the most common pattern):
ws.send(JSON.stringify({
  type:    "chat",
  room:    "general",
  message: "Hi everyone!",
  timestamp: Date.now(),
}));

// Receive and parse JSON:
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Message type:", data.type);

  if (data.type === "chat") {
    displayMessage(data.message, data.from);
  } else if (data.type === "users") {
    updateUserList(data.users);
  }
};

Send only when readyState is OPEN, and queue anything sent earlier so it goes out from onopen. The ChatRoom.send() below checks readyState but then silently drops early messages. A queue keeps them instead:

const ws = new WebSocket("ws://localhost:8765/ws");
const outbox = [];

function send(msg) {
  const data = JSON.stringify(msg);
  if (ws.readyState === WebSocket.OPEN) ws.send(data);
  else outbox.push(data);                          // not open yet: queue it
}

ws.onopen = () => {
  while (outbox.length) ws.send(outbox.shift());   // flush the queue once connected
};
ws.onmessage = (e) => console.log(e.data);

send({ type: "join", room: "general" });
// echo: {"type":"join","room":"general"}     (from a local echo server)

A simple chat example

class ChatRoom {
  constructor(url) {
    this.ws = new WebSocket(url);
    this.setupHandlers();
  }

  setupHandlers() {
    this.ws.onopen    = () => console.log("Joined chat");
    this.ws.onmessage = (e) => this.handleMessage(JSON.parse(e.data));
    this.ws.onclose   = ()  => console.log("Left chat");
  }

  handleMessage(data) {
    switch (data.type) {
      case "message": displayChat(data.user, data.text); break;
      case "join":    showNotification(`${data.user} joined`); break;
      case "leave":   showNotification(`${data.user} left`);   break;
    }
  }

  send(text) {
    if (this.ws.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify({ type: "message", text }));
    }
  }

  leave() { this.ws.close(1000, "User left"); }
}

Try It Yourself

// WebSocket — persistent two-way connection
// (This demo runs in the browser — connects to a real echo server)

const ws = new WebSocket("wss://echo.websocket.events");

ws.onopen = () => {
  console.log("Connected!");
  ws.send("Hello from JavaScript!");
  ws.send(JSON.stringify({ type: "ping", timestamp: Date.now() }));
};

ws.onmessage = (event) => {
  console.log("Received:", event.data);
  // event.data can be string or Blob (binary)
};

ws.onerror = (error) => {
  console.error("WebSocket error");
};

ws.onclose = (event) => {
  console.log(`Closed: code=${event.code} reason="${event.reason}"`);
  // Common close codes:
  // 1000 = normal closure
  // 1001 = going away (page navigation)
  // 1006 = abnormal closure (no close frame received)
};

// Send data:
// ws.send("string message");
// ws.send(JSON.stringify({ type: "chat", text: "hello" }));
// ws.send(new ArrayBuffer(8));  // binary data

// Check connection state:
// ws.readyState === WebSocket.CONNECTING  (0) — connecting
// ws.readyState === WebSocket.OPEN        (1) — connected
// ws.readyState === WebSocket.CLOSING     (2) — closing
// ws.readyState === WebSocket.CLOSED      (3) — closed

// Close explicitly:
// ws.close(1000, "Done");  // code, reason

Reconnection, heartbeats, and binary data

Automatic reconnection

class ReconnectingWebSocket {
  constructor(url, options = {}) {
    this.url        = url;
    this.maxDelay   = options.maxDelay   ?? 30000;
    this.baseDelay  = options.baseDelay  ?? 1000;
    this.attempt    = 0;
    this.handlers   = { open: [], message: [], close: [], error: [] };
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = (e) => {
      this.attempt = 0;  // reset backoff on successful connect
      this.handlers.open.forEach(h => h(e));
    };

    this.ws.onmessage = (e) => this.handlers.message.forEach(h => h(e));
    this.ws.onerror   = (e) => this.handlers.error.forEach(h => h(e));

    this.ws.onclose = (e) => {
      this.handlers.close.forEach(h => h(e));
      if (e.code !== 1000) {  // 1000 = intentional close, don't reconnect
        const delay = Math.min(this.baseDelay * 2 ** this.attempt, this.maxDelay);
        this.attempt++;
        console.log(`Reconnecting in ${delay}ms (attempt ${this.attempt})`);
        setTimeout(() => this.connect(), delay);
      }
    };
  }

  on(event, handler) { this.handlers[event]?.push(handler); return this; }
  send(data)         { this.ws.readyState === 1 && this.ws.send(data); }
  close()            { this.ws.close(1000); }
}

Heartbeat — keep connections alive

// Some proxies kill idle connections. Send a ping every 30 seconds:
let pingInterval;

ws.onopen = () => {
  pingInterval = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: "ping" }));
    }
  }, 30000);
};

ws.onclose = () => {
  clearInterval(pingInterval);
};

Binary data with WebSockets

// Send binary (ArrayBuffer or Blob):
ws.binaryType = "arraybuffer";  // default is "blob"

ws.onmessage = (event) => {
  if (typeof event.data === "string") {
    // Text message
    handleText(event.data);
  } else {
    // Binary message (ArrayBuffer if binaryType = "arraybuffer")
    const view = new Int16Array(event.data);
    handleAudioSamples(view);
  }
};

WebSocket spec, handshake, and vs SSE

WebSocket handshake (RFC 6455)

WebSocket starts as an HTTP/1.1 upgrade request. The client sends:

GET /ws HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

// Server responds:
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=  // SHA-1 of key + GUID

WebSocket vs Server-Sent Events (SSE)

// SSE — server pushes to client only (one-way), uses HTTP:
const sse = new EventSource("/api/events");
sse.onmessage = (e) => console.log(e.data);
sse.addEventListener("price", (e) => updatePrice(JSON.parse(e.data)));
// Auto-reconnects, works through proxies, HTTP/2 multiplexed

// Use SSE when: server → client only (notifications, live feeds)
// Use WebSocket when: bidirectional (chat, games, collaborative editing)

// WebSocket close codes (RFC 6455 §7.4):
// 1000 Normal closure
// 1001 Going away (navigating away)
// 1002 Protocol error
// 1003 Unsupported data type
// 1008 Policy violation
// 1011 Internal server error
// 4000-4999 Application-defined codes

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.