Reference

EventSource API

Compressed browser surface. Normative details live in the WHATWG interface section.

Construct

const es = new EventSource("/events");
// CORS cookies:
const es2 = new EventSource("https://api.example.com/events", {
  withCredentials: true,
});

Always a GET-style stream fetch (no body, no custom headers API).
Request may send Accept: text/event-stream; cache mode is no-store.
Starts in readyState === EventSource.CONNECTING (0).

readyState

Constant	Value	Meaning
`CONNECTING`	0	Not open yet, or reconnecting after a drop
`OPEN`	1	Stream open; events can dispatch
`CLOSED`	2	Dead; UA will not reconnect

Events

es.addEventListener("open", () => { /* readyState → OPEN */ });

// Default event type from the wire (no event: field)
es.onmessage = (e) => {
  console.log(e.data);       // string
  console.log(e.lastEventId);
  console.log(e.origin);
};

// Named types require addEventListener("name", …)
es.addEventListener("job-progress", (e) => {
  JSON.parse(e.data);
});

es.onerror = () => {
  // Fires on reconnect path AND on fatal failure.
  // Inspect es.readyState: CONNECTING = retrying, CLOSED = stopped.
};

es.close(); // → CLOSED, stops retries

What opens vs fails (spec)

Announce open: HTTP 200 + Content-Type: text/event-stream
Fail (no reconnect): wrong status, wrong type, aborted fatal error, or you called close()
Reestablish: many network drops / end of body → error event, CONNECTING, wait retry, fetch again (may send Last-Event-ID)
Stop reconnects (server): HTTP 204 No Content (among other non-stream responses that fail the connection)

Cleanup pattern (SPA)

useEffect(() => {
  const es = new EventSource("/events");
  es.onmessage = (e) => setState(JSON.parse(e.data));
  return () => es.close();
}, []);