Getting started

Server-sent events (SSE) is a standardised protocol that allows web-servers to push data (characterized as events) to a client without the client having to request it immediately before.

Using SSE can allow for significant savings in bandwidth and battery life on portable devices and will work with your existing infrastructure as it operates directly over the HTTP protocol without the need for the connection upgrade that WebSockets and HTTP/2 do (but can also be used with HTTP/2!).

Compared to WebSockets it has comparable performance and bandwidth usage, especially over HTTP/2, and natively includes event ID generation and automatic reconnection when clients are disconnected.

• Comparison: Server-sent Events vs WebSockets vs Polling
• WHATWG standards section for server-sent events
• MDN guide to server-sent events

Use your own framework

This guide uses the Express web-server in its code examples, but Better SSE works with any web-server framework that uses the underlying Node HTTP module. For example usage with other popular frameworks, see the Recipes section.

How does it work?

SSE works by a client connecting to a server using the EventSource interface. The server then indicates in its response headers that it will send back data in a stream of events and keeps the connection open indefinitely until it is closed by the client. From this point the server is free to continuously write data to the open connection and the EventSource will emit events with the sent data.

1. Client makes a request to the server using EventSource.
2. Server responds with the Content-Type header set to text/event-stream.
3. Client emits the open event and is ready to receive data.
4. Server continually writes text data to the open connection.
5. Client receives data and emits events on the EventSource instance.
6. Client terminates connection by calling the close method.

The technology can be used for things for things such as live notifications, news tickers, chat rooms, shout-boxes, event logs, progress bars, etc.

Install

Better SSE is shipped as a package on npm. You can install it with any Node package manager.

npm

npm install better-sse

Yarn

yarn add better-sse

pnpm

pnpm add better-sse

TypeScript types are included in the package distribution. No need to install from DefinitelyTyped for TypeScript users!

Create a session

Sessions simply represent an open connection between a client and the server. The client will first make a request to the server, and the server will open a session that it will push data to the client with.

First import the module:

ESModules / TypeScript

import { createSession } from "better-sse";

CommonJS

const { createSession } = require("better-sse");

Then create a session when the client makes a request on the specified route (GET /sse in this case):

app.get("/sse", async (req, res) => {
  const session = await createSession(req, res);
});

Now that we have an active session we can use it to push an event to the client:

session.push("Hello world!", "ping");

This will push an event named ping (but this can be any string) with the string Hello world! as its associated data.

Note

If you do not specify an event name, the event name is set to message.

Connect from the client

From your client-side code you can now connect to the server at the defined path.

Tip

It is highly recommended you use an EventSource polyfill that allows for backwards compatibility with older browsers as well as giving you extra features such as request header modification and improved error handling.

First we open a connection to the server to begin receiving events from it:

const eventSource = new EventSource("/sse");

Then we can attach an event listener to listen for the event our server is going to send:

eventSource.addEventListener("ping", (event) => {
  console.log(`${event.type} | ${event.data}`);
});

If you check your browser console you will now see ping | "Hello world!" logged to the console. Easy!

Note

Data is serialized as JSON by default. You can use JSON.parse(data) to get the real value of the event data.

You can find a reference to the received event object interface under the MessageEvent page on MDN.

Examples See the full code from this guide and other demo projects using Better SSE.