HTML Server-Sent Events

Introduction

Server-Sent Events (SSE) let a server push updates to a web page over a single, long-lived HTTP connection. This is ideal for live news tickers, sports scores, stock prices, notifications, and dashboards—anywhere the browser needs fresh data without constantly asking the server “anything new yet?”

SSE is simpler than WebSockets when you only need server → client communication. This tutorial covers the wire format, a Node.js server, the browser EventSource API, and minimal Try It demos you can run without setting up a backend.

What You’ll Learn

What Are Server-Sent Events?

Server-Sent Events (SSE) is a web technology where the server sends updates to the client as they happen. The client opens one HTTP connection and keeps it open; the server writes new messages whenever data changes.

Unlike polling (repeated fetch calls every few seconds), SSE is efficient: one connection, many updates. Unlike WebSockets, SSE is text-based, works through most HTTP proxies, and only flows in one direction—which is exactly what many live feeds need.

How Do Server-Sent Events Work?

SSE works over ordinary HTTP. The server responds with Content-Type: text/event-stream and keeps the connection open. Each message is plain text with a simple structure:

• data: — the payload (one or more lines; required for default messages).
• event: — optional event name (defaults to message).
• id: — optional id so the client can resume after reconnect.
• retry: — optional reconnection delay in milliseconds.
• Blank line — two newline characters (\n\n) end each event.

Example on the wire:

data: Stock price is 142.50

event: alert
data: Trading halted

The browser’s EventSource parses this stream and fires JavaScript events you can handle.

Setting Up Server-Sent Events

On the server, set headers for a streaming response and write data: lines followed by a blank line. Flush output so the client receives events immediately.

Here is a minimal Node.js example that sends the current time every second:

const http = require('http');

http.createServer(function (req, res) {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  });

  var timer = setInterval(function () {
    res.write('data: ' + new Date().toLocaleTimeString() + '\n\n');
  }, 1000);

  req.on('close', function () {
    clearInterval(timer);
  });
}).listen(8080, function () {
  console.log('SSE server on http://localhost:8080');
});

Run with node sse-server.js, then point your page’s EventSource at http://localhost:8080.

Receiving Events on the Client Side

Use the EventSource API in the browser. The default message event fires for plain data: lines:

var eventSource = new EventSource('http://localhost:8080');

eventSource.onmessage = function (event) {
  console.log('New message:', event.data);
};

eventSource.onopen = function () {
  console.log('SSE connection opened');
};

Call eventSource.close() when the page no longer needs updates (for example when navigating away).

Reconnecting Automatically

A key feature of SSE is automatic reconnection. If the network drops, EventSource retries after a short delay. Listen for errors to show status in your UI:

eventSource.onerror = function (event) {
  console.error('EventSource failed — browser will retry');
  // readyState: 0 = connecting, 1 = open, 2 = closed
  if (eventSource.readyState === EventSource.CLOSED) {
    console.log('Connection closed permanently');
  }
};

The server can suggest a retry interval with retry: 3000\n\n (wait 3 seconds before reconnecting).

Handling Different Event Types

Send a named event from the server with the event: field. On the client, use addEventListener instead of onmessage:

// Server
res.write('event: customEvent\n');
res.write('data: This is a custom event\n\n');

// Client
eventSource.addEventListener('customEvent', function (event) {
  console.log('Custom event:', event.data);
});

Default unnamed events still trigger onmessage. Named events do not.

Security Considerations

SSE rides on HTTP, so apply the same security practices as any web API:

• Use HTTPS in production so stream data cannot be read or modified on the network.
• Validate and escape data before inserting into HTML—treat event.data like any untrusted string (use textContent, not innerHTML).
• Authenticate streams when content is private (cookies or tokens on the same origin).
• Configure CORS if the EventSource URL is on a different domain than your page.
• Rate-limit connections on the server to prevent abuse of open streams.

Examples Gallery

Five short examples from server setup to a full clock page. Try It Yourself demos use plain HTML with no CSS and simulate the stream so you can practice client handlers without running Node.js.

const http = require('http');

http.createServer(function (req, res) {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  });

  setInterval(function () {
    res.write('data: ' + new Date().toLocaleTimeString() + '\n\n');
  }, 1000);
}).listen(8080);

SSE server on http://localhost:8080
(data: 3:45:12 PM sent every second)

var eventSource = new EventSource('http://localhost:8080');

eventSource.onmessage = function (event) {
  console.log('New message:', event.data);
};

New message: 3:45:12 PM
New message: 3:45:13 PM

eventSource.onerror = function () {
  console.error('Connection error. Retrying...');
};

Connection error. Retrying...

// Server sends:
// event: news
// data: Breaking story
// (blank line)

eventSource.addEventListener('news', function (event) {
  console.log('News:', event.data);
});

News: Breaking story

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Server-Sent Events Example</title>
</head>
<body>
  <h1>Real-Time Clock</h1>
  <div id="clock"></div>

  <script>
    var eventSource = new EventSource('http://localhost:8080');

    eventSource.onmessage = function (event) {
      document.getElementById('clock').textContent = event.data;
    };

    eventSource.onerror = function () {
      console.error('Connection error. Retrying...');
    };
  </script>
</body>
</html>

Real-Time Clock
3:45:18 PM

🚀 Common Use Cases

• Live news and sports tickers — push headlines as they publish.
• Stock and crypto prices — stream price changes to dashboards.
• Notifications — alert users without polling every few seconds.
• Progress updates — long server jobs report status (% complete).
• Social feeds — new posts appear at the top in real time.
• Monitoring dashboards — server metrics streamed to ops teams.

📝 Notes

• SSE is one-way—only server → client on that connection.
• Internet Explorer does not support EventSource; all modern browsers do.
• Some older proxies buffer responses; SSE needs streaming-friendly infrastructure.
• Browser limit: roughly six SSE connections per domain (similar to HTTP/1.1).
• For bidirectional chat or games, consider WebSockets instead.
• Try It demos simulate streams so you can learn handlers without a backend.

💡 Best Practices