What is eventsource?
The eventsource npm package is a Node.js implementation of the EventSource client, which is used for receiving server-sent events (SSE). It allows clients to subscribe to a stream of updates from a server over an HTTP connection. The package is designed to be compliant with the W3C EventSource specification and is typically used for real-time data feeds, such as live notifications, stock prices updates, or any other continuous data stream.
What are eventsource's main functionalities?
Connecting to an SSE server
This code demonstrates how to connect to an SSE server and listen for messages. The 'onmessage' handler is called whenever a new message is received, and the 'onerror' handler is called if there's an error with the connection.
const EventSource = require('eventsource');
const es = new EventSource('http://example.com/events');
es.onmessage = function(event) {
console.log(event.data);
};
es.onerror = function(err) {
console.error('EventSource failed:', err);
};
Listening for specific event types
This code snippet shows how to listen for specific event types using the 'addEventListener' method. In this example, the client listens for 'userupdate' events and processes the received data.
const EventSource = require('eventsource');
const es = new EventSource('http://example.com/events');
es.addEventListener('userupdate', function(event) {
const userData = JSON.parse(event.data);
console.log('User update:', userData);
});
Reconnecting after connection loss
This example illustrates the automatic reconnection feature of the EventSource API. The 'onopen' handler is called when the connection is successfully established, and the 'onerror' handler indicates that the connection has been lost and a reconnection attempt will be made.
const EventSource = require('eventsource');
const es = new EventSource('http://example.com/events');
es.onopen = function() {
console.log('Connection to server opened.');
};
es.onerror = function() {
console.log('Connection lost, the browser will automatically attempt to reconnect.');
};
Other packages similar to eventsource
sse-client
The sse-client package is another implementation of the EventSource API for Node.js. It provides similar functionality for connecting to SSE servers and handling server-sent events. Compared to eventsource, it may have different API nuances or additional features, but the core functionality remains the same.
oceanwind
Oceanwind is not a direct alternative to eventsource, but it is an example of a package that uses server-sent events to provide real-time updates to clients. It is a library for managing real-time communication between servers and clients, and it may include an SSE implementation as part of its feature set.
eventsource



WhatWG/W3C-compatible server-sent events/eventsource client. The module attempts to implement an absolute minimal amount of features/changes beyond the specification.
If you're looking for a modern alternative with a less constrained API, check out the eventsource-client
package.
Installation
npm install --save eventsource
Supported engines
- Node.js >= 20
- Chrome >= 63
- Safari >= 11.3
- Firefox >= 65
- Edge >= 79
- Deno >= 1.30
- Bun >= 1.1.23
Basically, any environment that supports:
If you need to support older runtimes, try the 2.x
branch/version range (note: 2.x branch is primarily targetted at Node.js, not browsers).
Usage
import {EventSource} from 'eventsource'
const es = new EventSource('https://my-server.com/sse')
es.addEventListener('notice', (event) => {
console.log(event.data)
})
es.addEventListener('update', (event) => {
console.log(event.data)
})
es.addEventListener('message', (event) => {
console.log(event.data)
})
setTimeout(() => {
es.close()
}, 10_000)
TypeScript
Make sure you have configured your TSConfig so it matches the environment you are targetting. If you are targetting browsers, this would be dom
:
{
"compilerOptions": {
"lib": ["dom"],
},
}
If you're using Node.js, ensure you have @types/node
installed (and it is version 18 or higher). Cloudflare workers have @cloudflare/workers-types
etc.
The following errors are caused by targetting an environment that does not have the necessary types available:
error TS2304: Cannot find name 'Event'.
error TS2304: Cannot find name 'EventTarget'.
error TS2304: Cannot find name 'MessageEvent'.
Migrating from v1 / v2
See MIGRATION.md for a detailed migration guide.
Extensions to the WhatWG/W3C API
Message and code properties on errors
The error
event has a message
and code
property that can be used to get more information about the error. In the specification, the Event
es.addEventListener('error', (err) => {
if (err.code === 401 || err.code === 403) {
console.log('not authorized')
}
})
Specify fetch
implementation
The EventSource
constructor accepts an optional fetch
property in the second argument that can be used to specify the fetch
implementation to use.
This can be useful in environments where the global fetch
function is not available - but it can also be used to alter the request/response behaviour.
const es = new EventSource('https://my-server.com/sse', {
fetch: (input, init) =>
fetch(input, {
...init,
headers: {
...init.headers,
Authorization: 'Bearer myToken',
},
}),
})
HTTP/HTTPS proxy
Use a package like node-fetch-native
to add proxy support, either through environment variables or explicit configuration.
import {fetch} from 'node-fetch-native/proxy'
const es = new EventSource('https://my-server.com/sse', {
fetch: (input, init) => fetch(input, init),
})
Allow unauthorized HTTPS requests
Use a package like undici
for more control of fetch options through the use of an Agent
.
import {fetch, Agent} from 'undici'
await fetch('https://my-server.com/sse', {
dispatcher: new Agent({
connect: {
rejectUnauthorized: false,
},
}),
})
License
MIT-licensed. See LICENSE.