Dead simple, dependency-less, spec-compliant server-sent events implementation written in TypeScript.
npm install better-sseevent-source-polyfill and eventsource-polyfill.
sh
npm install better-sse
`
`sh
yarn add better-sse
`
`sh
pnpm add better-sse
`
`sh
bun add better-sse
`
`sh
deno install jsr:@mwid/better-sse
`
_Better SSE ships with types built in. No need to install from DefinitelyTyped for TypeScript users!_
Usage
The examples below show usage with Express and Hono, but Better SSE works with any web-server framework that uses the Node HTTP module or the Fetch API.
See the Recipes section of the documentation for use with other frameworks and libraries.
---
Use sessions to push events to clients:
`typescript
// Server - Express
import { createSession } from "better-sse"
app.get("/sse", async (req, res) => {
const session = await createSession(req, res)
session.push("Hello world!", "message")
})
`
`typescript
// Server - Hono
import { createResponse } from "better-sse"
app.get("/sse", (c) =>
createResponse(c.req.raw, (session) => {
session.push("Hello world!", "message")
})
)
`
`typescript
// Client
const eventSource = new EventSource("/sse")
eventSource.addEventListener("message", ({ data }) => {
const contents = JSON.parse(data)
console.log(contents) // Hello world!
})
`
Use channels to send events to many clients at once:
`typescript
import { createSession, createChannel } from "better-sse"
const channel = createChannel()
app.get("/sse", async (req, res) => {
const session = await createSession(req, res)
channel.register(session)
channel.broadcast("A user has joined.", "join-notification")
})
`
Use batching to send multiple events at once for improved performance and lower bandwidth usage:
`typescript
await session.batch(async (buffer) => {
await buffer.iterate(["My", "huge", "event", "list"])
})
`
Loop over sync and async iterables and send each value as an event:
`typescript
const iterable = [1, 2, 3]
await session.iterate(iterable)
`
Pipe readable stream data to the client as a stream of events:
`typescript
const stream = Readable.from([1, 2, 3])
await session.stream(stream)
`
---
Check the API documentation and live examples for information on getting more fine-tuned control over your data such as managing event IDs, data serialization, event filtering, dispatch controls and more!
Documentation
See the documentation website for guides, usage examples, compatibility information and an API reference.
Contributing
This library is always open to contributions whether it be code, bug reports, documentation or anything else.
Please submit suggestions, bugs and issues to the GitHub issues page.
For code or documentation changes submit a pull request on GitHub.
Local Development
Install Node (with n):
`bash
curl -L https://git.io/n-install | bash
n auto
`
Install dependencies (with pnpm):
`bash
npm i -g pnpm
pnpm i
`
Run tests (with Vitest):
`bash
pnpm t
`
Lint and format (with Biome):
`bash
pnpm lint
pnpm format
`
Bundle for distribution (with tsup):
`bash
pnpm build
`
Documentation
The documentation is built with Astro and Starlight. Its source is located in the docs directory.
Install dependencies:
`bash
cd docs
pnpm i
`
Run development server:
`bash
pnpm dev
`
Build for distribution:
`bash
pnpm build
``