The EventSource API¶
The browser side of SSE is one object: EventSource. It has a tiny surface —
this page covers all of it.
Create and listen¶
const es = new EventSource("/events");
// events with no `event:` field land here
es.onmessage = (e) => console.log("message:", e.data);
// named events need addEventListener
es.addEventListener("tick", (e) => console.log("tick:", e.data));
es.addEventListener("stock", (e) => console.log("stock:", e.data));
The e in every handler is a MessageEvent:
| Property | Contains |
|---|---|
e.data |
The data: payload — always a string. Parse JSON yourself. |
e.lastEventId |
The id: of this event (or the last id seen, for id-less events). |
e.type |
The event name — "message", "tick", whatever event: said. |
e.origin |
Origin of the stream. |
Parse once, parse early
e.data is a string. JSON.parse(e.data) is the universal first line of
most handlers — our demo does exactly that.
Lifecycle: open / error / close¶
es.onopen = () => setStatus("open");
es.onerror = () => {
// Fires on connection failure AND on every failed reconnect attempt.
// Check readyState to tell them apart:
if (es.readyState === EventSource.CONNECTING) {
setStatus("reconnecting"); // a retry is already scheduled — do nothing
} else {
setStatus("closed"); // CLOSED — it gave up (e.g. non-SSE response)
}
};
// You close it; it never closes itself except on fatal errors.
es.close();
readyState values:
| Constant | Value | Meaning |
|---|---|---|
EventSource.CONNECTING |
0 | Connecting or reconnecting — retries in progress |
EventSource.OPEN |
1 | Connected, events flowing |
EventSource.CLOSED |
2 | Dead — you called close() or a fatal error occurred |
What EventSource does for you¶
- ✅ Opens the connection and sets
Accept: text/event-stream - ✅ Parses the wire format (blank-line dispatch, multi-line data, comments)
- ✅ Reconnects automatically on drops, honoring the
retry:field - ✅ Sends
Last-Event-IDon reconnects — for free - ✅ Buffers correctly across TCP chunk boundaries (half an event never fires)
What it does not do — the sharp edges¶
- ❌ GET only. No POST, no custom body.
- ❌ No custom headers in the browser API.
Authorization: Bearer …is not possible with nativeEventSource— auth comes from cookies or a token in the query string (see production). - ❌ No reconnection of a half-read stream — if the server crashes mid-event, that partial event is discarded.
- ❌ No pause/backpressure API — events queue in the browser if your handler is slow.
- ❌ HTTP/1.1 connection limits: ~6 connections per origin per browser. Two tabs with two streams each = 4 used. HTTP/2 removes this limit.
Need headers or POST?
The community standard is fetch() + a manual SSE parser, or the
@microsoft/fetch-event-source
package (~2KB) — same protocol, full control. The wire format is the same;
you just lose auto-reconnect and Last-Event-ID handling (reconnect logic
becomes yours).
Query params are your config surface¶
Since headers are off-limits, encode client choices in the URL:
Our demo uses this for channel subscriptions — the checkboxes rebuild the URL and reconnect.
Minimal robust client — the pattern our demo uses¶
let es;
function connect() {
if (es) es.close();
es = new EventSource("/events");
es.onopen = () => ui.status("open");
es.onerror = () =>
ui.status(es.readyState === EventSource.CONNECTING ? "reconnecting" : "closed");
es.addEventListener("tick", (e) => ui.tick(JSON.parse(e.data)));
}
window.addEventListener("beforeunload", () => es?.close()); // tidy
connect();
Check your understanding¶
Inside addEventListener('stock', e => …), what is e.data?
Where do events without an event: field land?
Inside onerror, es.readyState === EventSource.CONNECTING means…
Which are real limitations of the native EventSource API? (select all)
Next: reconnection & heartbeats — what happens when things go wrong (they will).