Server-Sent Events (SSE)

Server-Sent Events (SSE) let a server push a continuous stream of text events to the browser over a single long-lived HTTP response. The client uses the EventSource API to open the connection, receive messages, and automatically reconnect when the stream drops.

SSE is one-directional (server → client), uses ordinary HTTP/HTTPS, and speaks a simpletext/event-stream format. That makes it a strong fit for notifications, live dashboards, log tails, progress updates, and LLM token streaming — cases where the client does not need a full-duplex WebSocket.

This guide covers SSE vs WebSocket vs polling, the EventSource constructor and withCredentials, readyState, open/message/error events, custom event types, lastEventId and reconnection, the retry field, server stream format, Node/Express and Next.js route handler examples, auth limitations and workarounds, CORS, connection limits, use cases, cleanup, fetch-based streaming alternatives, retry strategies, security, and best practices.

Create a connection with new EventSource(url) or new EventSource(url, { withCredentials: true }). Same-origin cookies are sent by default for same-origin URLs; cross-origin cookie auth requires withCredentials: true and matching CORS.

EventSource.readyState reports connection status using numeric constants mirrored on the instance:

Three built-in event channels cover most clients. open fires when the stream is ready. message fires for events without a custom event: field (type message). error fires on network failures and after connection loss — EventSource typically transitions to CONNECTING and retries unless you called close().

Servers can set an event: field. Those events do not hit the default message listener — register a listener for that event name instead. This keeps progress, heartbeats, and domain events cleanly separated.

When the server includes an id: field, the browser stores it as EventSource.lastEventId. On reconnect, the browser automatically sends that value in the Last-Event-ID HTTP header so the server can resume without duplicating or skipping events.

A line like retry: 5000 tells the browser how many milliseconds to wait before reconnecting after a drop. Send it early in the stream (or periodically) to tune backoff without client-side timers.

The response must use Content-Type: text/event-stream. Each event is one or more field lines ending with a blank line. Comments start with : and keep proxies/load balancers from timing out idle connections when used as heartbeats.

Disable response buffering, set SSE headers, write frames, and clear timers when the client disconnects. Flush after each write when behind proxies that buffer.

In the App Router, return a ReadableStream with SSE headers from a route handler. Respect request.signal for cancellation when the client disconnects.

Because EventSource cannot attach custom headers, Bearer-token APIs need an alternative. Common patterns:

Cross-origin SSE requires standard CORS headers on the stream response. If you use withCredentials: true, you cannot mirror * for Access-Control-Allow-Origin — echo the specific origin and set Access-Control-Allow-Credentials: true.

Browsers limit concurrent HTTP/1.1 connections per origin (often six). Each EventSource counts against that budget. Opening many SSE endpoints on the same origin can stall other requests. HTTP/2 multiplexing reduces the pain, but you should still multiplex logical channels over one SSE connection when possible.

Call source.close() when the component unmounts, the user logs out, or the job completes. After close, readyState is CLOSED and the browser will not reconnect. On the server, listen for request close/abort to free timers and backpressure.

When you need Authorization headers or POST bodies, use fetch + ReadableStream and parse SSE frames yourself. You lose automatic reconnect unless you implement it.

EventSource retries automatically on transient failures. Still handle permanent errors: HTTP 401/403 often still surface as error events depending on browser — validate tickets before opening, and close the source if you detect auth failure via a side channel. For fetch-based streams, implement exponential backoff with jitter and honor Last-Event-ID.