sse.js: Server-Sent Events for Node.js

0.0.8 verified Sat Apr 25 auth: no javascript abandoned

The `sse` package (einaros/sse.js) provides a server-side implementation of the HTML5 Server-Sent Events (SSE) specification for Node.js applications. SSE enables a server to push data to web pages over HTTP, facilitating real-time communication without the overhead of WebSockets for unidirectional data flows. Currently at version `0.0.8`, this package is considered abandoned, with its last release dating back approximately eight years (published December 2017, but copyright 2011) and minimal activity on its GitHub repository. Its primary differentiator was offering a straightforward, low-level API to integrate SSE directly with Node.js's native HTTP server, abstracting the complexities of managing event streams and client connections. Given its age, it relies exclusively on CommonJS and is likely incompatible with modern Node.js versions and ES module adoption. Users seeking SSE functionality in current Node.js environments should consider actively maintained alternatives such as `@fastify/sse`, `sse-channel`, or `better-sse` due to potential compatibility, security, and feature limitations.

Common errors

error Error: Cannot find module 'sse' ↓

cause This error typically occurs if the package has not been installed (`npm install sse`) or if `import { SSE } from 'sse'` is used in an ES module environment when the package only offers CommonJS exports.

fix

Run npm install sse to ensure the package is available. If using ES modules, rewrite your import to const SSE = require('sse'); in a CommonJS-compatible file, or switch to a modern SSE library with ESM support.

error TypeError: Cannot read properties of undefined (reading 'on') ↓

cause This error can occur if the `SSE` constructor is called with an invalid or `undefined` HTTP server object, or if Node.js HTTP server APIs have changed significantly since the package's last update.

fix

Verify that http.createServer correctly returns a server instance and that the server is properly listening before passing it to new SSE(server). Given the package's age, fundamental incompatibilities with modern Node.js http module APIs are likely; consider migrating to an alternative SSE library.

Warnings

breaking This package is designed for very old Node.js versions (>=0.4.0) and is largely incompatible with modern Node.js runtimes due to significant API changes and lack of maintenance. Direct usage may lead to runtime errors or unexpected behavior on current Node.js versions. ↓

fix Avoid using this package in new projects. For existing projects, consider migrating to actively maintained SSE libraries compatible with modern Node.js, such as `@fastify/sse`, `sse-channel`, or `better-sse`.

gotcha The `sse` package is unmaintained and marked as inactive/discontinued. This poses significant security risks as it will not receive updates for vulnerabilities or bug fixes. Its codebase has not been audited for modern security concerns. ↓

fix Do not use this package in production environments. Migrate to a well-maintained and actively developed SSE solution that addresses modern security standards.

gotcha The package exclusively supports CommonJS (`require()`) syntax. It does not provide ES module exports and will cause runtime errors if `import` statements are used, making integration into modern JavaScript projects cumbersome. ↓

fix Ensure `require('sse')` is used in CommonJS contexts. For projects using ES modules, a wrapper might be necessary, but migration to a modern, ESM-compatible SSE library is strongly recommended.

Install

npm install sse

yarn add sse

pnpm add sse

Imports

SSE
wrong
```
import { SSE } from 'sse';
import SSE from 'sse';
```
correct
```
const SSE = require('sse');
```
This package is CommonJS-only and explicitly designed for older Node.js runtimes (v0.4.0+). Attempting to use ES module import syntax (`import ... from 'sse'`) will result in a runtime error. It does not provide a default export, nor does it support named exports via ES modules.

Quickstart

Sets up a basic Node.js HTTP server that integrates `sse.js` to handle Server-Sent Events. It sends an initial message upon client connection and then broadcasts periodic updates every three seconds, demonstrating unidirectional server-to-client communication.

var SSE = require('sse')
  , http = require('http');

var server = http.createServer(function(req, res) {
  res.writeHead(200, {'Content-Type': 'text/plain'});
  res.end('okay');
});

server.listen(8080, '127.0.0.1', function() {
  console.log('Server listening on http://127.0.0.1:8080');
  var sse = new SSE(server);
  sse.on('connection', function(client) {
    console.log('Client connected. Sending initial message...');
    client.send('hi there!');

    // Example: Send a message every 3 seconds
    let counter = 0;
    const interval = setInterval(() => {
      client.send(`Message from server: ${counter++}`);
    }, 3000);

    client.on('close', () => {
      console.log('Client disconnected.');
      clearInterval(interval);
    });
  });
});

// Client-side JavaScript (for browser to connect):
// var es = new EventSource("/sse");
// es.onmessage = function (event) {
//   console.log("Received: " + event.data);
// };