Registry / http-networking / better-sse

better-sse

JSON →
library0.16.1jsnpmunverified

Better SSE is a robust, dependency-less, and spec-compliant implementation of Server-Sent Events (SSE) written entirely in TypeScript. It provides a streamlined, framework-agnostic solution for pushing data from a server to clients over HTTP, making it an alternative to WebSockets for unidirectional data flows. Currently stable at version 0.16.1, the project demonstrates a consistent release cadence with updates addressing compatibility, new features like connection adapters and event batching, and continuous type improvements. Key differentiators include its full TypeScript support, extensive documentation, 100% test coverage, and compatibility across various Node.js frameworks and runtimes (e.g., Express, Hono, Fastify, Bun, Deno), operating directly over the HTTP protocol to reduce bandwidth and complexity compared to other real-time solutions.

npm install better-sse
INSTALL
IMPORT
SIG · BETTER-SSE
B
better-sse
http-networkingjavascriptv0.16.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createSession
import { createSession } from 'better-sse'
const { createSession } = require('better-sse')
ESM is the primary import style; CommonJS `require` might have issues in older versions or specific environments, especially before v0.14.0.
createChannel
import { createChannel } from 'better-sse'
import createChannel from 'better-sse'
`createChannel` is a named export. Attempting a default import will result in `undefined`.
Session
import type { Session } from 'better-sse'
import { Session } from 'better-sse'
`Session` is a TypeScript type, not a runtime value. Import it using `import type` to avoid bundling issues or runtime errors.

This quickstart demonstrates setting up a basic Server-Sent Events endpoint using Express. It initializes a session for a new client connection, sends an initial greeting, and then periodically pushes updates until the client disconnects.

import { createSession } from 'better-sse'; import express from 'express'; const app = express(); const port = 3000; app.get('/events', (req, res) => { // Ensure client doesn't cache the response res.setHeader('Cache-Control', 'no-cache'); res.setHeader('Content-Type', 'text/event-stream'); res.setHeader('Connection', 'keep-alive'); const session = createSession(req, res); // Optionally, send an initial event session.push('Hello from the server!', 'greeting'); // Periodically send data let counter = 0; const interval = setInterval(() => { if (session.isClosed()) { clearInterval(interval); console.log('Session closed, stopping updates.'); return; } session.push(`Data update ${counter++}`, 'update'); }, 2000); // Handle client disconnect session.on('close', () => { clearInterval(interval); console.log('Client disconnected.'); }); }); app.listen(port, () => { console.log(`SSE server listening at http://localhost:${port}`); console.log('Connect with a browser using EventSource: new EventSource("http://localhost:3000/events")'); });
Debug
Known issues
breakingIntroduction of 'Connection Adapters' in v0.16.0 changed how connections are managed. While not strictly API breaking for simple use cases, custom or complex integrations might need to adapt to this new abstraction, especially when running on environments that do not fully emulate Node's HTTP APIs.
fix
Review the documentation on 'Connection Adapters' if encountering issues with specific frameworks or runtimes. Update to v0.16.1 for fixes related to Node HTTP/1 and HTTP/2 compatibility issues in emulated environments.
affects: >=0.16.0
gotchaPrior to v0.14.0, there were minor issues when importing the package into an ES Module (ESM) environment. Consumers might have encountered unexpected behavior or errors related to module resolution.
fix
Upgrade to better-sse v0.14.0 or newer to ensure correct ESM import behavior. For older versions, carefully check module resolution configurations (e.g., `"type": "module"` in `package.json`, `tsconfig.json` settings).
affects: <0.14.0
gotchaWhen using frameworks that do not fully implement Node's HTTP/1 or HTTP/2 Compatibility APIs (e.g., some edge runtimes or newer frameworks), v0.16.0 could crash due to missing `setNoDelay` methods.
fix
Upgrade to v0.16.1 or newer, which includes a fix for this crash by gracefully handling the absence of `setNoDelay`.
affects: 0.16.0
gotchaEvent name suggestions for `Session` and `Channel` event listeners were improved in v0.12.1. Older versions might lack proper TypeScript autocompletion for event names, leading to potential typos or runtime errors.
fix
Update to v0.12.1 or later to benefit from enhanced TypeScript type inference and suggestions for event names, improving developer experience and reducing errors.
affects: <0.12.1
Errors
Common errors & fixes
TypeError: createSession is not a function
Attempting to use `require` for a package primarily designed for ES modules, or incorrect named import.
fix
Ensure you are using ES module imports: `import { createSession } from 'better-sse';`. If in a CommonJS context, consider configuring your project to support ESM or using an older version if available (though newer versions are ESM-first).
Headers already sent. Cannot set headers after they are sent to the client.
Attempting to modify response headers after SSE session has started or other middleware has sent initial headers.
fix
Ensure `res.setHeader()` calls for `Cache-Control`, `Content-Type`, and `Connection` are made *before* `createSession(req, res)` or any data is written to the response stream. This often means placing them early in your SSE route handler.
Error: read ECONNRESET
Client disconnected abruptly, leading to a connection reset by the peer on the server side.
fix
Implement proper session cleanup by listening to the `close` event on the `Session` object (`session.on('close', () => { /* cleanup resources */ });`) to stop sending events or clear timers specific to that client.
Upgrade
Version history
0.16.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources
better-sse — npm install better-sse · libregistry