Server-Sent Events (SSE) Cheat Sheet

Updated 2026-05-28

Next Topic: Serverless Backend Patterns Cheat Sheet

🧠Study flashcards on this topic94 cards · spaced repetition→

Server-Sent Events (SSE) is a standard web technology that enables servers to push real-time updates to browser clients over a persistent HTTP connection using the text/event-stream content type. Unlike WebSockets, SSE provides unidirectional server-to-client streaming using familiar HTTP infrastructure, making it simpler to implement and deploy for scenarios like live notifications, dashboards, LLM token streaming, and progress updates. The key advantage is automatic reconnection: when a connection drops, the browser's EventSource API automatically attempts to reconnect, optionally resuming from the last event using the Last-Event-ID header. With HTTP/3 (QUIC) now prevalent, SSE benefits from eliminated head-of-line blocking and no connection limits — making it the default transport for most AI streaming APIs and real-time feeds in 2026.

What This Cheat Sheet Covers

This topic spans 15 focused tables and 121 indexed concepts, 94 flashcards. Below is a complete table-by-table outline of this topic, spanning foundational concepts through advanced details.

Table 1: Core Concepts & EventSource APITable 2: Event Stream Format & SyntaxTable 3: Connection Management & LifecycleTable 4: Event Handlers & State ManagementTable 5: Named Events & Event IDsTable 6: Reconnection & Stream ResumptionTable 7: CORS & AuthenticationTable 8: HTTP Protocol & TransportTable 9: Proxy & Server ConfigurationTable 10: Performance & ScalabilityTable 11: Browser Support & Fetch API AlternativesTable 12: Use Cases & PatternsTable 13: SSE vs WebSockets vs WebTransport ComparisonTable 14: Best Practices & OptimizationTable 15: Security Considerations

Quick IndexSubscribe to unlock

A jump-to index of every table row in this cheat sheet.

Mind MapSubscribe to unlock

An interactive map of every table and concept in this topic.

Table 1: Core Concepts & EventSource API

The EventSource interface is SSE's browser-native client; it abstracts connection management, event parsing, and reconnection so you only need to handle incoming events. Understanding what the API does automatically — and where it falls short — determines when to use it versus a fetch-based alternative.

Concept	Example	Description
EventSource interface	`const es = new EventSource('/events')`	• Browser API that opens a persistent HTTP connection and receives server-pushed events • handles parsing, reconnection, and event dispatching automatically.
text/event-stream content type	`Content-Type: text/event-stream`	• Required HTTP response header that signals SSE protocol • charset UTF-8 is implicit and should not be explicitly added as it can break some implementations.
Automatic reconnection	Browser reconnects on disconnect	• `EventSource` automatically attempts to reconnect if the connection drops • configurable via the `retry` field sent from server.
Unidirectional streaming	Server → Client only	• SSE is server-to-client only • client sends regular HTTP requests if bidirectional communication is needed (contrast with WebSocket's full-duplex design).
UTF-8 encoding	All messages must be UTF-8 text	• SSE exclusively supports text data encoded as UTF-8 • binary data requires Base64 encoding or similar text-safe transformation before transmission.
Event-driven model	`es.onmessage = (e) => {...}`	• Events are dispatched to registered listeners • supports both default `message` events and custom named event types via `addEventListener()`.
Connection persistence	`Connection: keep-alive` header	• Long-lived HTTP connection remains open indefinitely • requires server and proxy configuration to prevent premature timeout.
Page Visibility API integration	Close SSE when tab hidden, reopen on focus	• `fetch-event-source` automatically closes the SSE connection when the document is hidden (tab minimized) and reconnects when visible again • reduces unnecessary server load; opt-in behavior on native `EventSource`.

Table 2: Event Stream Format & Syntax

The SSE wire format is plain UTF-8 text — human-readable and debuggable with curl -N. Each event is a block of field: value lines terminated by a blank line (\n\n); understanding exactly how fields combine and how the double-newline acts as an event boundary is essential to avoid malformed streams.

Field	Example	Description
data field	`data: Hello World\n\n`	• The message payload • required field that sets `event.data` on the client • double newline (`\n\n`) terminates the event and triggers dispatch.

The rest of this section is part of the full cheat sheet

Table 3: Connection Management & Lifecycle

Opening and closing SSE connections correctly on both client and server prevents resource leaks. The readyState property tracks the connection phase, and cleaning up via close() on the client — plus detecting disconnection on the server — is the foundation of robust lifecycle management.

Concept	Example	Description
Creating EventSource	`const es = new EventSource(url)`	• Opens persistent connection to specified URL • immediately begins attempting connection and fires `onopen` when established.

The rest of this section is part of the full cheat sheet

Table 4: Event Handlers & State Management

SSE exposes three core event callbacks — onopen, onmessage, onerror — plus addEventListener for named events. Correctly interpreting readyState inside onerror distinguishes a transient network hiccup (browser will retry) from a terminal failure (needs user notification).

Handler	Example	Description
onmessage	`es.onmessage = (e) => {...}`	• Handles default unnamed events (events without `event:` field) • receives MessageEvent with `data`, `lastEventId`, `origin` properties.

The rest of this section is part of the full cheat sheet

Table 1: Core Concepts & EventSource API

Concept	Example	Description
EventSource interface	`const es = new EventSource('/events')`	• Browser API that opens a persistent HTTP connection and receives server-pushed events • handles parsing, reconnection, and event dispatching automatically.
text/event-stream content type	`Content-Type: text/event-stream`	• Required HTTP response header that signals SSE protocol • charset UTF-8 is implicit and should not be explicitly added as it can break some implementations.
Automatic reconnection	Browser reconnects on disconnect	• `EventSource` automatically attempts to reconnect if the connection drops • configurable via the `retry` field sent from server.
Unidirectional streaming	Server → Client only	• SSE is server-to-client only • client sends regular HTTP requests if bidirectional communication is needed (contrast with WebSocket's full-duplex design).
UTF-8 encoding	All messages must be UTF-8 text	• SSE exclusively supports text data encoded as UTF-8 • binary data requires Base64 encoding or similar text-safe transformation before transmission.
Event-driven model	`es.onmessage = (e) => {...}`	• Events are dispatched to registered listeners • supports both default `message` events and custom named event types via `addEventListener()`.
Connection persistence	`Connection: keep-alive` header	• Long-lived HTTP connection remains open indefinitely • requires server and proxy configuration to prevent premature timeout.
Page Visibility API integration	Close SSE when tab hidden, reopen on focus	• `fetch-event-source` automatically closes the SSE connection when the document is hidden (tab minimized) and reconnects when visible again • reduces unnecessary server load; opt-in behavior on native `EventSource`.

Table 2: Event Stream Format & Syntax

Field	Example	Description
data field	`data: Hello World\n\n`	• The message payload • required field that sets `event.data` on the client • double newline (`\n\n`) terminates the event and triggers dispatch.

Table 3: Connection Management & Lifecycle

Concept	Example	Description
Creating EventSource	`const es = new EventSource(url)`	• Opens persistent connection to specified URL • immediately begins attempting connection and fires `onopen` when established.

Table 4: Event Handlers & State Management

Handler	Example	Description
onmessage	`es.onmessage = (e) => {...}`	• Handles default unnamed events (events without `event:` field) • receives MessageEvent with `data`, `lastEventId`, `origin` properties.