EventSource: Browser Support, Features, Limitations

What is EventSource?

EventSource is a JavaScript interface defined by the WHATWG HTML Living Standard that opens a long-lived HTTP connection to a server and receives a one-way stream of UTF-8 text events. The browser parses the text/event-stream response, fires message events on the page, and reconnects automatically on network drops.

Which browsers does EventSource support?

EventSource ships in every modern browser, with global support near 97% across desktop and mobile. Once a browser shipped the interface, the spec did not break across versions, so feature detection is the only check production code needs.

What are the key features of EventSource?

EventSource bakes streaming, reconnection, and event routing into a single small interface so the page does not have to wire any of it by hand. The features below cover what the constructor gives you out of the box.

• One-line streaming connection: The constructor new EventSource(url) opens a persistent HTTP connection and starts parsing the text/event-stream response without any extra setup. The page only needs to attach a message listener to start receiving server-pushed data.
• Automatic reconnection with Last-Event-ID: The browser reconnects on network drops with a default 3000-millisecond interval. On reconnect, the browser sends the Last-Event-ID header so the server can resume the stream from the last delivered event without losing or duplicating messages.
• Named events through addEventListener: The server can label each event with an event: field, and the page routes those labels with stream.addEventListener("price", handler) instead of switching on a payload field. Unlabeled events fire on the default message channel.
• readyState lifecycle and close(): The interface exposes CONNECTING (0), OPEN (1), and CLOSED (2) constants on the readyState property, plus a close() method that tears down the connection without firing another reconnect.
• withCredentials for cross-origin auth: Passing { withCredentials: true } to the constructor sends cookies and HTTP authentication headers on cross-origin streams, mirroring the same flag from the Fetch and XHR APIs for CORS-aware servers.
• Server-controlled retry interval: A retry: 10000 line in the event stream tells the browser to wait 10 seconds before the next reconnect, which lets the server back off clients during peak load without any client code change.

EventSource vs WebSockets: what is the difference?

EventSource and WebSockets both keep a long-lived connection open between a browser and a server, but the trade-offs cluster around direction, transport, and payload type. The table below compares the two on the dimensions that drive the design decision.

What are the limitations of EventSource?

EventSource trades flexibility for a tiny API, so the rough edges show up the moment a project needs anything beyond a one-way GET stream. The painful failures cluster around HTTP method, headers, connection caps, and proxy behavior.

• GET only, no request body: The constructor only issues a GET request, so any state has to ride in the URL query string. Long auth tokens or large filter payloads either bloat the URL or force a polyfill like fetch-event-source that opens an SSE-style stream over a POST.
• No custom headers: The native API only accepts the withCredentials option, so Authorization, X-Tenant, or X-API-Key headers cannot be set. Same-origin endpoints can lean on cookies, but cross-origin streams usually need a reverse proxy that injects the headers server-side.
• Six-connection cap on HTTP/1.1: The browser caps open connections per origin at six over plain HTTP/1.1, so the seventh EventSource opened against the same origin queues until another closes. HTTP/2 lifts the cap to the negotiated SETTINGS_MAX_CONCURRENT_STREAMS value.
• UTF-8 text only: The wire format is text/event-stream, so binary payloads have to be base64-encoded on the server and decoded in the page. WebSockets carry binary frames natively when the workload needs it.
• Proxies buffer streaming responses: Many corporate forward proxies, NGINX defaults, and CDN edges buffer responses until the body finishes, which collapses an SSE stream into one giant payload at disconnect. Set X-Accel-Buffering: no on the response and disable any compression filter on the path.
• No native progress or backpressure: The page cannot signal slow consumers, so a client that falls behind keeps receiving events into the browser buffer until memory pressure forces a reconnect. Servers usually rate-limit or paginate by sequence ID instead.
• Internet Explorer and Opera Mini are out: Both browsers never shipped EventSource, so any audience that still includes them needs the eventsource npm polyfill or a long-polling fallback wired into the same code path.

In my experience, the limitation that bites teams hardest is proxy buffering. An SSE feed that streams cleanly on localhost goes silent in staging because NGINX or a CDN edge holds the response until the connection closes. Set X-Accel-Buffering: no, disable gzip on the route, and verify a chunked response with curl before you ship.

How do you check if a browser supports EventSource?

A one-line feature check on the window object tells the page whether to wire native EventSource or load a polyfill. Paste this snippet into the DevTools console of Chrome, Edge, Firefox, or Safari to confirm support and watch a single event arrive from a public test stream.

// Paste this into the DevTools console to confirm EventSource support and watch a test stream.
if ("EventSource" in window) {
  console.log("EventSource is supported in this browser.");

  const stream = new EventSource("https://sse.dev/test");

  stream.addEventListener("open", () => {
    console.log("Stream opened, readyState =", stream.readyState);
  });

  stream.addEventListener("message", (event) => {
    console.log("Event received:", event.data);
    stream.close();
    console.log("Stream closed after first event.");
  });

  stream.addEventListener("error", () => {
    console.log("EventSource error: the test endpoint may be unreachable from this network.");
  });
} else {
  console.log("EventSource is not supported in this browser.");
}

If the console logs that EventSource is supported but the open event never fires, the network path is blocking long-lived HTTP responses. Check the Network tab for a 200 response with Content-Type: text/event-stream, then verify no proxy on the path is buffering or compressing the body.

Citations

All EventSource version numbers and platform notes in this guide come from these primary sources:

• WHATWG HTML Living Standard - Server-sent events: html.spec.whatwg.org/multipage/server-sent-events.html
• MDN Web Docs - EventSource interface: developer.mozilla.org/en-US/docs/Web/API/EventSource
• MDN Web Docs - Using server-sent events: developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events
• MDN Web Docs - EventSource constructor: developer.mozilla.org/en-US/docs/Web/API/EventSource/EventSource
• MDN Web Docs - Server-sent events overview: developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
• Wikipedia - Server-sent events: en.wikipedia.org/wiki/Server-sent_events
• Chrome Platform Status - Server-sent events: chromestatus.com/feature/5704494382383104
• Firefox release notes - Firefox 6: mozilla.org/en-US/firefox/6.0/releasenotes
• Microsoft Learn - Microsoft Edge release notes: learn.microsoft.com/en-us/deployedge/microsoft-edge-relnote-stable-channel
• WebKit blog - Safari release notes: webkit.org/blog
• RFC 8441 - Bootstrapping WebSockets with HTTP/2: datatracker.ietf.org/doc/html/rfc8441