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
• Can I use… Server-sent events

Use your own framework

These guides use Express and Hono in their code examples, but Better SSE works with any web-server framework that uses the Node HTTP module or the Fetch API. 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 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 and the JSR. You can install it with any package manager.

npm

npm install better-sse

Yarn

yarn add better-sse

pnpm

pnpm add better-sse

Bun

bun add better-sse

Deno

deno install jsr:@mwid/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):

Express

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

Hono

app.get("/sse", (c) =>
    createResponse(c.req.raw, (session) => {
        // ...
    })
)

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 the string Hello world! to the client as an event named ping (defaults to message if no name is given.)

createSession or createResponse?

If your framework uses the Fetch API use createResponse, otherwise use createSession

After creating a session we must wait for the underlying connection to be initialized before we can begin pushing events to it.

When using the Node HTTP/1 or HTTP/2 APIs we can flush the response headers and any other preamble data ahead of time and thus immediately begin pushing events to the session:

// Express uses the Node HTTP/1 API
app.get("/sse", async (req, res) => {
    const session = await createSession(req, res)
    session.push("Hello world!")
})

When using a Fetch-based framework, however, we must first return a Response object from our route handler for the session to able to connect and send data.

We can either do this manually:

// Hono uses the Fetch API
app.get("/sse", async (c) => {
    const session = await createSession(c.req.raw)

    session.addListener("connected", () => {
        session.push("Hello world!")
    })

    return session.getResponse()
})

Or use the shorthand createResponse utility function:

app.get("/sse", (c) =>
    createResponse(c.req.raw, (session) => {
        session.push("Hello world!")
    })
)

The previous two code snippets are equivalent.

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, improved error handling and greater control over reconnection behaviour.

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

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

Event data is serialized to JSON with JSON.stringify by default. You can use JSON.parse(event.data) to get its real value.

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

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