WebSocket & Server-Sent Events

Some pages change while you watch. A score goes up, or a chat message appears, and you never press refresh. Often the new data arrives as a short line of text from the server. Here is one such line.

const line = "data: tea";
console.log(line.startsWith("data:"));
console.log(line.slice(6));

Line 1 stores one line of text: data: tea. Line 2 checks that the line starts with data:, so it prints true. Line 3 cuts off the first six characters, data: with its space, and prints tea.

Later in this lesson, the browser does this cutting for you. It hands your code the rest of the line, tea, as event.data. The value stays text. The browser does not turn it into JSON.

Real-time means “tell me when it happens”

So far, most network code you have seen follows one pattern, called request and response:

• Your code asks the server for something. This is the request.
• The server sends back one answer. This is the response.
• Then that exchange is over.

This works well for loading a profile, saving a form, or getting JSON with fetch(). A real-time page is different. It shows new data as soon as the server has it, without a refresh.

JavaScript has four common ways to get these updates. This lesson covers each one:

• Short polling: the page asks the server again and again, on a timer.
• Long polling: the page asks once, and the server waits to answer until it has news.
• Server-Sent Events (SSE): the server keeps sending text updates to the page.
• WebSocket: the page and the server stay connected, and both can send messages at any time.

The four ways differ in a few things:

• Who can send: only the server, or both sides.
• Whether they reconnect by themselves after the connection drops.
• Whether they can carry binary data: raw bytes, such as an image, instead of text.
• How well they pass through a proxy. A proxy is a computer between the browser and the server that passes messages along.
• How much code you have to write yourself.

Short polling is the simplest way. A timer asks the server every few seconds: “Anything new?” It works almost everywhere, because each ask is a normal HTTP request. HTTP is the same way of talking to a server that fetch() uses.

Short polling has two costs:

• When nothing changes, the requests still go out and come back empty.
• A new update has to wait until the next timer tick.

Long polling changes one thing. The browser sends a request, but the server does not answer right away. It holds the request until it has news, or until a time limit runs out. This time limit is called a timeout.

As soon as the answer arrives, the browser handles it and sends the next request. Each message still costs one request. But quiet times no longer fill up with empty “no change” answers.

const updateAt = 18;
const nextPoll = 20;
console.log(nextPoll - updateAt, "seconds late");
console.log("long polling: answer when the update arrives");

Line 1 says the update happens at second 18. Line 2 says the next short-polling request goes out at second 20. Line 3 subtracts the two and prints 2 seconds late. Line 4 describes long polling. Its request is already waiting at the server, so the server can answer the moment the update happens. These numbers are a made-up example, not a real network clock.

1// Short polling: ask every 10 seconds2GET /updates?since=0  -> no change3GET /updates?since=0  -> update at 20s4 5// Long polling: ask once and wait6GET /updates?since=0  -> server holds7                         update at 18s

Long polling is useful in two cases:

• Old network equipment blocks connections that stay open, like WebSocket.
• The server is already built to answer ordinary requests, one at a time.

Long polling code needs the same care as other retry code: a loop, a timeout, and error handling. You saw this kind of retry code in the Async patterns lesson.

You create a WebSocket with new WebSocket(url, protocols):

• The url starts with wss://, like "wss://example.com/chat".
• The protocols argument is optional. It names the message format both sides agree to use, like "chat.v1".

First the browser and the server agree to connect. This first exchange is called the handshake. After it, both sides can send messages at any time. That is why chat, games with many players, shared documents, and other pages where the user also sends a lot usually use WebSocket.

A WebSocket is always in one of four states. It keeps its current state in a property called readyState, as a number from 0 to 3.

const states = ["CONNECTING", "OPEN", "CLOSING", "CLOSED"];
console.log(states[1]);
console.log(String(1));

Line 1 lists the four state names in number order. Line 2 prints states[1], the item at index 1, which is OPEN. Line 3 prints 1, the number for that state. The name and the number mean the same state. Printing them does not open anything, though. Only a real socket in the OPEN state can send.

When a WebSocket closes, it reports a close code: a number that says why it closed.

const closeCodes = { normal: 1000, goingAway: 1001, abnormal: 1006 };
console.log(closeCodes.normal);
console.log(closeCodes.abnormal);

Line 1 stores three common close codes in an object. Line 2 prints 1000, the code for a normal close. Line 3 prints 1006, the code for a connection that vanished without a proper close. The browser can report 1006 to your code. But your code is not allowed to send 1006 itself.

Step through one WebSocket from start to end below: create it, wait for it to open, send a message, get messages back, and close it.

1const socket = new WebSocket("wss://example.test/chat", "chat.v1");Run2 3socket.addEventListener("open", () => {4  socket.send("hello bots");5});6 7socket.addEventListener("message", (event) => {8  console.log(event.data);9});10 11socket.addEventListener("close", (event) => {12  console.log(event.code, event.reason);13});

A few more facts matter in real apps:

• send() takes text or binary data. Binary data can be a Blob, an ArrayBuffer, or a typed array. All three are ways to hold raw bytes.
• Calling send() while the socket is still CONNECTING throws an error named InvalidStateError.
• bufferedAmount is the number of bytes waiting to go out. You passed them to send(), but the browser has not sent them yet.
• Close code 1000 means a normal close. 1001 means one side is going away, for example because the page is closing. 1006 means the connection vanished; only the browser reports it.
• WebSocket never reconnects by itself.
• If the page was loaded over HTTPS, use a wss:// URL. It is the secure kind.

1const socket = new WebSocket("wss://example.test/chat", "chat.v1");2 3socket.addEventListener("open", () => {4  socket.send("Hello room!");5});6 7socket.addEventListener("message", (event) => {8  appendToLog(event.data);9});10 11socket.addEventListener("close", (event) => {12  showCloseCode(event.code, event.reason);13});

In the playground, the Drop connection button reports 1006, so you can see a connection vanish. The Reconnect with backoff button waits a little, then creates a new socket. Backoff means waiting longer after each failed try. Real apps also set a longest wait, check whether the device is online, and log the user in again when needed.

function retryDelay(attempt) {
  return Math.min(8000, 250 * 2 ** attempt);
}
console.log(retryDelay(0));
console.log(retryDelay(3));

Line 1 starts a function that takes the attempt number. Line 2 works out the wait in milliseconds:

• 2 ** attempt is 2 to the power of attempt: 1, 2, 4, 8, and so on. Times 250, that gives 250, 500, 1000, 2000. So the wait doubles with each attempt.
• Math.min returns the smaller of its two numbers. So the wait never goes above 8000.

Line 4 prints 250 for attempt 0. Line 5 prints 2000 for attempt 3, because 250 × 2 × 2 × 2 is 2000. The limit matters during a long outage. Without it, the next wait could grow to hours.

A heartbeat is a tiny message that asks “Still there?” on a quiet connection. If no answer comes back, the app knows the connection is broken.

const appHeartbeat = "ping";
console.log(appHeartbeat);
console.log("pong");

Line 1 picks the app's heartbeat message, "ping". Line 2 prints it. Line 3 prints the answer the app expects back, pong. These are normal app messages. The WebSocket protocol has its own ping signal too, but page JavaScript cannot send it.

Server-Sent Events (SSE) let a server keep sending text to the page. In the browser, you use an object called EventSource. The server answers one normal HTTP request, but it never finishes the answer. It keeps adding text to it. The answer is marked with the type text/event-stream.

Messages go one way only: from the server to the browser. That is fine when the page mostly listens. In return, the browser does several jobs for you:

• It reconnects by itself if the connection drops.
• It tells your code the name of each event.
• It remembers the id of the last event.
• It follows the server's advice on how long to wait before reconnecting.

The stream is plain text, with one field on each line:

• event: names the event. You listen for it with addEventListener(name, ...).
• data: holds the message. Your code reads it as event.data.
• id: sets lastEventId. When the browser reconnects, it sends this id back in a Last-Event-ID header. A header is a named note sent along with a request. It tells the server where to start again.
• retry: says how many milliseconds to wait before reconnecting.
• A blank line ends one event and sends it to your code.

An event with no event: line goes to onmessage. A named event does not. It only reaches a listener added for its own name.

1const source = new EventSource("data:text/event-stream,...");2 3source.addEventListener("score", (event) => {4  console.log(event.lastEventId, event.data);5});6 7source.onmessage = (event) => {8  console.log("message", event.data);9};10 11source.close(); // stop reconnecting

1retry: 12002id: kickoff3event: score4data: Owls 0, Foxes 05 6id: goal-17event: score8data: Owls 1, Foxes 09 10id: note-111data: Halftime snacks are ready

SSE carries only text, but that text can be JSON. It fits notification lists, live sports scores, progress messages, logs, and dashboards. To send cookies with the request, write new EventSource(url, { withCredentials: true }).

One more limit: with the older HTTP/1.1, a browser keeps only a few connections open to one site, often six. Many tabs with SSE open can use them all up. The newer HTTP/2 usually avoids this, because many streams share one connection.

A transport is the way updates travel between the server and the page. To choose one, start with direction: who needs to send?

The table compares the choices. Read down a column to learn one choice, or across a row to compare one question.

A simple rule: pick the simplest thing that does the job.

• If updates can wait a while, use polling.
• If the server sends text and the page only listens, start with SSE.
• If both sides need to send at any moment, use WebSocket.
• If the network equipment blocks these, long polling still works.

Where you will use this

In a real app, the code around the connection matters as much as the connection. It has to:

• read each message,
• update what the page shows,
• show whether the connection is working,
• close the connection when that part of the page goes away,
• and avoid adding the same listener twice.

The examples below leave out framework code, so the connection code is easy to see.

1const socket = new WebSocket("wss://example.com/chat", "chat.v1");2 3socket.addEventListener("open", () => {4  socket.send(JSON.stringify({ type: "join", room: "lobby" }));5});6 7socket.addEventListener("message", (event) => {8  const message = JSON.parse(event.data);9  renderChatMessage(message);10});11 12socket.addEventListener("close", (event) => {13  scheduleReconnect(event.code);14});

Line 1 opens the socket. Line 4 runs once the socket is open and sends a join message as JSON text. Line 8 turns each message that arrives back into an object with JSON.parse. Line 13 runs when the socket closes and plans a new connection. renderChatMessage and scheduleReconnect stand for your own app's functions.

1const feed = new EventSource("/notifications/stream", {2  withCredentials: true,3});4 5feed.addEventListener("notification", (event) => {6  const item = JSON.parse(event.data);7  addNotification(item);8});9 10feed.onerror = () => {11  showStatus("Reconnecting...");12};

Lines 1 to 3 open the stream and send cookies with it. Line 5 listens for events named notification, and line 6 reads each one as JSON. Line 10 runs when the connection has a problem. The browser is already reconnecting by itself, so the code only shows a message.

1function chooseRealtimeTransport({ clientTalks, binary, textUpdates, rareUpdates }) {2  if (clientTalks || binary) return "WebSocket";3  if (textUpdates) return "Server-Sent Events";4  if (rareUpdates) return "Polling";5  return "Long polling";6}

Line 2 picks WebSocket when the page must send too, or when the data is binary. Line 3 picks Server-Sent Events for text updates from the server. Line 4 picks polling when updates are rare. Line 5 uses long polling for everything else.

One step is easy to forget: closing. When a part of the page no longer needs updates, call socket.close() or eventSource.close(). Otherwise a hidden tab, or a part of the page you already removed, keeps getting data and doing work.

Common misconceptions

• “Real-time always means WebSocket.” If data only goes from the server to the browser, SSE is often simpler. It also reconnects by itself.
• “SSE can replace every WebSocket.” SSE goes one way and carries only text. To send from the page, use a separate request, or use WebSocket.
• “WebSocket reconnects by itself.” It does not. After the close event, that socket is finished. Your code must create a new one.
• “I should send close code 1006.” No. 1006 is kept for the browser, to report a connection that vanished. Your code may not send it.
• “Long polling is fake real-time.” It is a real, useful way to get updates, especially as a backup plan. Its cost is one full request for each message.
• “A heartbeat fixes every network problem.” A heartbeat only finds a quiet connection that broke. It does not make sure messages arrive, and you still need retries.

Key takeaways

• Short polling asks on a timer. Long polling sends one request, and the server waits to answer it.
• WebSocket is one open, two-way connection. Send only when it is OPEN, and reconnect in your own code.
• Server-Sent Events are a one-way text stream. They have named events, ids, and a retry delay, and they reconnect by themselves.
• Choose by who sends, how often, text or binary, what the network allows, and what should happen when the connection fails.

Real-time code means picking the simplest connection that reliably brings updates when users need them.

Up next: XMLHttpRequest, the older way to make requests. You will still see it in old code.