HTML Server‑Sent Events (SSE)

Real‑Time Apps, Patterns, Performance & Best Practices

Building real‑time web experiences often conjures images of WebSockets, complex bidirectional protocols, and hefty infrastructure. Yet for many common scenarios—live news feeds, stock tickers, notification streams, progress updates—Server‑Sent Events (SSE) offer a remarkably simple, reliable, one‑way push channel from server to browser. With a minimal API surface (the EventSource interface) plus the strength of HTTP/2 multiplexing, automatic reconnection, and built‑in message ID tracking, SSE can power scalable real‑time apps without the overhead of full WebSocket management.

In this deep dive, you’ll learn:

• How SSE works under the hood and its core concepts.
• Basic client & server code patterns in Node.js (Express) and other environments.
• Comparisons with WebSockets and long polling to choose the right tool.
• Advanced event streams: custom events, retry directives, last‑event‑ID resumption.
• Error handling and reconnection strategies, plus fallbacks for unsupported browsers.
• Scalability patterns: batching, heartbeats, idle‑timeout disconnects, and HTTP/2.
• Security & CORS best practices to safely expose streams.
• Performance tweaks: back‑off algorithms, monitoring, and pub/sub integration.
• Real‑world use cases: dashboards, CMS live blogs, file upload progress, notifications.
• Framework integration (React, Vue, Svelte) and developer tooling tips.
• FAQs covering binary data, one‑way semantics, browser limits, and more.

By the end, you’ll have a comprehensive Server‑Sent Events guide—from zero to production‑ready streaming—with actionable patterns and code snippets to build real‑time browser updates that are both robust and easy to maintain.

1. How SSE Works & Its Core Concepts

Server‑Sent Events leverage a persistent HTTP connection that the browser opens via the EventSource API. Unlike a traditional fetch request that completes once the server returns a response, SSE keeps the connection alive indefinitely. The server writes text in a specific format—text/event-stream—emitting discrete messages which the client parses and dispatches as events.

Connection Lifecycle

• Client:

const evtSource = new EventSource("/stream");
evtSource.onopen    = () => console.log("SSE connection opened.");
evtSource.onmessage = e => console.log("Message:", e.data);
evtSource.onerror   = e => console.error("SSE error", e);

const evtSource = new EventSource("/stream");
evtSource.onopen    = () => console.log("SSE connection opened.");
evtSource.onmessage = e => console.log("Message:", e.data);
evtSource.onerror   = e => console.error("SSE error", e);

• Server:
  • Returns HTTP status 200 with header

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

• Generates messages using the SSE format:

id: 1
event: update
data: {"price": 123.45}

id: 2
data: Hello, world!
retry: 5000

id: 1
event: update
data: {"price": 123.45}

id: 2
data: Hello, world!
retry: 5000

• Blank line (\n\n) terminates each message.

SSE Message Fields

• data: The payload (one or multiple lines).
• event: (Optional) Custom event type.
• id: (Optional) Message identifier; sent back via Last-Event-ID header on reconnect.
• retry: (Optional) Tells the browser to wait n milliseconds before reconnecting.

Automatic Reconnection

When the connection drops (network glitch, server restart), EventSource automatically reconnects after the last retry interval, sending Last-Event-ID so the server can resume without data loss.

2. Basic Client & Server Code

Client‑Side (Browser)

HTML:

<script>
  // Open SSE stream
  const source = new EventSource("/api/notifications");

  source.onopen = () => {
    console.log("Connected to SSE");
  };

  source.onmessage = (e) => {
    // Default 'message' event
    console.log("New message:", e.data);
    displayNotification(JSON.parse(e.data));
  };

  source.addEventListener("priceUpdate", (e) => {
    // Custom event type
    const { symbol, price } = JSON.parse(e.data);
    updateTicker(symbol, price);
  });

  source.onerror = (err) => {
    console.error("SSE error:", err);
    // Optionally close on fatal error
    // source.close();
  };
</script>

<script>
  // Open SSE stream
  const source = new EventSource("/api/notifications");

  source.onopen = () => {
    console.log("Connected to SSE");
  };

  source.onmessage = (e) => {
    // Default 'message' event
    console.log("New message:", e.data);
    displayNotification(JSON.parse(e.data));
  };

  source.addEventListener("priceUpdate", (e) => {
    // Custom event type
    const { symbol, price } = JSON.parse(e.data);
    updateTicker(symbol, price);
  });

  source.onerror = (err) => {
    console.error("SSE error:", err);
    // Optionally close on fatal error
    // source.close();
  };
</script>

Server‑Side (Node.js + Express)

JS:

const express = require("express");
const app = express();

app.get("/api/notifications", (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
  });

  // Heartbeat to keep connection alive (every 20s)
  const heartbeat = setInterval(() => res.write(":\n\n"), 20000);

  let id = 0;
  const sendEvent = (event, data) => {
    id++;
    res.write(`id: ${id}\n`);
    if (event) res.write(`event: ${event}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // Example: push a message every 5 seconds
  const timer = setInterval(() => {
    sendEvent("notification", { text: "Hello at " + new Date().toISOString() });
  }, 5000);

  // Clean up on client disconnect
  req.on("close", () => {
    clearInterval(timer);
    clearInterval(heartbeat);
    res.end();
  });
});

app.listen(3000, () => console.log("SSE server listening on 3000"));

const express = require("express");
const app = express();

app.get("/api/notifications", (req, res) => {
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
  });

  // Heartbeat to keep connection alive (every 20s)
  const heartbeat = setInterval(() => res.write(":\n\n"), 20000);

  let id = 0;
  const sendEvent = (event, data) => {
    id++;
    res.write(`id: ${id}\n`);
    if (event) res.write(`event: ${event}\n`);
    res.write(`data: ${JSON.stringify(data)}\n\n`);
  };

  // Example: push a message every 5 seconds
  const timer = setInterval(() => {
    sendEvent("notification", { text: "Hello at " + new Date().toISOString() });
  }, 5000);

  // Clean up on client disconnect
  req.on("close", () => {
    clearInterval(timer);
    clearInterval(heartbeat);
    res.end();
  });
});

app.listen(3000, () => console.log("SSE server listening on 3000"));

Note: Always flush output immediately; frameworks like Express buffer by default—use lower‑level APIs or ensure flush after res.write().

3. SSE vs WebSockets & Long Polling

• Choose SSE when…
  • You need simple one‑way updates (news feeds, metrics).
  • You want auto‑reconnect and message ordering out of the box.
  • HTTP infrastructure (proxies, load balancers) already handles long‑lived connections.
• Choose WebSockets when…
  • You need full duplex communication (chat apps, collaborative editors).
  • Low latency, binary data, or custom protocols are required.
• Long polling remains a fallback for environments where SSE or WebSockets are blocked. Polling at intervals (e.g., every 2s) is less efficient and can overwhelm servers under scale.

4. Handling Advanced Event Streams

Custom Event Types

By specifying event: in the server stream:

Editevent: priceUpdate
data: {"symbol":"AAPL","price":150.23}

Editevent: priceUpdate
data: {"symbol":"AAPL","price":150.23}

Client registers via addEventListener:

source.addEventListener("priceUpdate", e => {
  const { symbol, price } = JSON.parse(e.data);
  console.log(`Price of ${symbol}: $${price}`);
});

source.addEventListener("priceUpdate", e => {
  const { symbol, price } = JSON.parse(e.data);
  console.log(`Price of ${symbol}: $${price}`);
});

Resume with id & Last-Event-ID

• Server includes an id: field per message.
• Browser sends Last-Event-ID header on reconnect.
• Server logic reads this header and skips already‑sent events:

app.get("/stream", (req, res) => {
  const lastId = Number(req.headers["last-event-id"] || 0);
  // Send events with id > lastId
});

app.get("/stream", (req, res) => {
  const lastId = Number(req.headers["last-event-id"] || 0);
  // Send events with id > lastId
});

Dynamic Retry Intervals

Server can adjust reconnection timing:

retry: 10000

retry: 10000

Browser waits 10 seconds before retrying instead of the default 3 seconds.

5. Error Handling & Reconnection

Client‑Side

source.onerror = (err) => {
  console.warn("SSE connection error", err);
  // Check readyState: 0=connecting, 1=open, 2=closed
  if (source.readyState === EventSource.CLOSED) {
    console.log("SSE closed by server—reconnecting manually.");
    setTimeout(() => {
      source = new EventSource(source.url);
    }, 5000);
  }
};

source.onerror = (err) => {
  console.warn("SSE connection error", err);
  // Check readyState: 0=connecting, 1=open, 2=closed
  if (source.readyState === EventSource.CLOSED) {
    console.log("SSE closed by server—reconnecting manually.");
    setTimeout(() => {
      source = new EventSource(source.url);
    }, 5000);
  }
};

Server‑Side

• Handle dropped connections (req.on("close")) to avoid memory leaks.
• Use robust network libraries (e.g., Node.js streams, Java NIO) to efficiently serve many open connections.

Fallbacks

Detect lack of SSE support:

if (!window.EventSource) {
  // Fallback to long polling or WebSocket polyfill
}

if (!window.EventSource) {
  // Fallback to long polling or WebSocket polyfill
}

Provide alternate endpoints (/poll) that respond with JSON every N seconds.

6. Scalability & Server Load Management

Connection Limits

• Browsers limit ~6 simultaneous connections per domain on HTTP/1.x.
• HTTP/2 multiplexing allows many SSE streams over a single TCP connection—significantly improving scale.

Batching & Heartbeats

• Batch multiple logical events into one SSE message if they occur close together.
• Heartbeat with comment lines (:keep-alive\n\n) every 15–30 seconds to prevent proxies from timing out.

Idle Disconnects

• Implement a TTL: if no data for X minutes, send a custom event: close then end the connection.
• Clients can reopen the stream on user activity.

Pub/Sub Integration

Ideal for horizontal scaling:

1. Backend workers publish events to a message broker (e.g., Redis Pub/Sub, Kafka).
2. SSE server subscribes to channels and pushes incoming messages to connected clients.

// Pseudocode
redis.subscribe("notifications");
redis.on("message", (channel, msg) => {
  clients.forEach(client => client.sendEvent("notification", msg));
});

// Pseudocode
redis.subscribe("notifications");
redis.on("message", (channel, msg) => {
  clients.forEach(client => client.sendEvent("notification", msg));
});

This decoupled architecture handles thousands of concurrent streams with modest resources.

7. Security & CORS Considerations

• HTTPS is mandatory to avoid mixed‑content errors and ensure data integrity.
• CORS: If SSE endpoint is on a different origin, configure headers:

Access-Control-Allow-Origin: https://yourapp.com
Access-Control-Allow-Credentials: true

Access-Control-Allow-Origin: https://yourapp.com
Access-Control-Allow-Credentials: true

In client:

const source = new EventSource("https://api.example.com/stream", { withCredentials: true });

const source = new EventSource("https://api.example.com/stream", { withCredentials: true });

• Authentication:
  • Use HTTP cookies (Secure, HttpOnly) or Authorization headers (JWT) when opening the stream.
  • Validate the token on each SSE connection attempt.
• Data Sanitization: Always escape or JSON‑stringify event data to prevent injection attacks.

8. Performance & Reliability Patterns

Back‑Off Strategy

When network errors occur, exponential back‑off prevents thundering reconnections:

let retry = 1000;
function connect() {
  const src = new EventSource("/stream");
  src.onerror = () => {
    src.close();
    setTimeout(connect, retry);
    retry = Math.min(retry * 2, 30000);
  };
}
connect();

let retry = 1000;
function connect() {
  const src = new EventSource("/stream");
  src.onerror = () => {
    src.close();
    setTimeout(connect, retry);
    retry = Math.min(retry * 2, 30000);
  };
}
connect();

Monitoring

• Server metrics: track active connections, message rates, backlog sizes.
• Client‑side logs: record reconnections and error codes for analytics.

Load Testing

Simulate thousands of clients to uncover bottlenecks—use tools like JMeter or k6, ensuring CPU, memory, and network bandwidth remain within acceptable thresholds.

9. Real‑World Use Cases

Live Dashboards & Notifications

Scenario: An admin panel that displays real‑time user activity (logins, errors).

• Server pushes JSON events: { user: "...", action: "login" }.
• Client appends rows to a live table and updates aggregate counters.

CMS Live Blogs

Scenario: Sports or news website that streams live commentary snippets.

• Editors post short updates; backend writes them into an SSE stream.
• Readers’ browsers instantly receive and display new paragraphs without polling.

Batch Upload Progress

Scenario: Large file or multiple file uploads with server‑side processing (e.g., virus scan, image resizing).

• Client initiates uploads via AJAX.
• Server streams progress events:

event: uploadProgress
data: {"file":"report.pdf","percent":45}

event: uploadProgress
data: {"file":"report.pdf","percent":45}

• Client updates progress bars in real time.

Real‑Time Metrics & IoT

Scenario: Monitoring sensors or application metrics (CPU, memory, throughput).

• A backend aggregator publishes telemetry to SSE clients.
• Dashboards display time‑series charts that update every second without full chart re‑renders.

10. Fallback Strategies & Polyfills

Not all environments support SSE (e.g., IE9–10, some corporate proxies). Implement layered fallbacks:

• Check EventSource Support:

if (window.EventSource) { // Use SSE } else { // Fallback to polling or WebSocket }

if (window.EventSource) { // Use SSE } else { // Fallback to polling or WebSocket }

• Long Polling:

async function poll() { const resp = await fetch("/api/stream/poll"); handle(resp.json()); setTimeout(poll, 2000); } poll();

async function poll() { const resp = await fetch("/api/stream/poll"); handle(resp.json()); setTimeout(poll, 2000); } poll();

• WebSocket Polyfill: Libraries like SockJS can emulate SSE using WebSockets or XHR long polling under the hood.

These strategies ensure broad compatibility while still delivering near‑real‑time updates.

11. Integrating with Modern Frameworks

React Example

JSX:

import { useEffect, useState } from "react";

function LiveFeed() {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    const src = new EventSource("/stream");
    src.onmessage = e => {
      setMessages(prev => [...prev, JSON.parse(e.data)]);
    };
    return () => src.close();
  }, []);

  return (
    <ul>
      {messages.map((m,i) => <li key={i}>{m.text}</li>)}
    </ul>
  );
}

import { useEffect, useState } from "react";

function LiveFeed() {
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    const src = new EventSource("/stream");
    src.onmessage = e => {
      setMessages(prev => [...prev, JSON.parse(e.data)]);
    };
    return () => src.close();
  }, []);

  return (
    <ul>
      {messages.map((m,i) => <li key={i}>{m.text}</li>)}
    </ul>
  );
}

Vue Example

JS:

export default {
  data: () => ({ events: [] }),
  created() {
    this.src = new EventSource("/updates");
    this.src.onmessage = e => this.events.push(JSON.parse(e.data));
  },
  beforeDestroy() {
    this.src.close();
  }
};

export default {
  data: () => ({ events: [] }),
  created() {
    this.src = new EventSource("/updates");
    this.src.onmessage = e => this.events.push(JSON.parse(e.data));
  },
  beforeDestroy() {
    this.src.close();
  }
};

Use your framework’s state management to funnel SSE events into stores (Redux, Vuex, Pinia), enabling components across the app to react.

12. Debugging & Monitoring

• Browser DevTools:
  • In Chrome’s Network panel, filter for EventStream to inspect frames.
  • View HTTP headers and streaming responses in real time.
• Client‑Side Logging: Instrument onopen, onmessage, onerror callbacks to track connection health.
• Server‑Side Tracing: Log connection opens, closes, and errors. Correlate with client logs for end‑to‑end debugging.
• Health Checks: Implement an HTTP endpoint (e.g., /health) that reports number of active SSE connections and queue depth—integrate into your monitoring dashboards.

13. FAQs

Q1: Why is SSE one‑way?
SSE uses plain HTTP streaming, optimized for server pushes. The browser cannot send messages over the same connection—use AJAX or WebSockets for bidirectional communication.

Q2: Can I send binary data?
No—SSE only transports UTF‑8 text. To send binary, encode as Base64 (with size and performance caveats) or switch to WebSockets.

Q3: How do I resume from the last missed event?
Use id: in server messages. On reconnect, the browser includes Last-Event-ID. Your server should track past events and replay those with id > lastEventId.

Q4: What about browser support and limits?
Supported in Chrome, Firefox, Edge, Safari, and IE10+. Limit ~6 concurrent connections per domain on HTTP/1.x; HTTP/2 lifts that restriction.

Q5: How do I handle network flapping?
Implement exponential back‑off in your onerror handler, avoid hammering servers, and optionally display UI alerts if reconnections exceed a threshold.

14. Conclusion

Server‑Sent Events provide a lightweight, robust, and scalable mechanism for one‑way, server‑to‑client real‑time updates. With native browser support, automatic reconnection, and HTTP/2 multip
lexing, SSE often outperforms polling or over‑engineered WebSocket solutions for live dashboards, news feeds, notifications, and progress streams.

Key best practices:

• Define clear message formats (id, event, data, retry).
• Manage connection lifecycles: heartbeats, idle timeouts, and graceful cleanup.
• Scale horizontally with pub/sub systems and HTTP/2 multiplexing.
• Secure with HTTPS, proper CORS, and authentication checks.
• Graceful fallbacks ensure compatibility on older browsers or restricted networks.

By following these patterns—custom events, batching, back‑off, monitoring, and framework integration—you’ll build real‑time browser updates that are not only performant but also maintainable and resilient. Embrace SSE for your next live‑data feature, and deliver seamless user experiences with minimal complexity.

About The Author

Pavan Kalyan

See author's posts