Eventsource-client NPM

eventsource-client

A modern, streaming client for server-sent events/eventsource.

Another one?

Yes! There are indeed lots of different EventSource clients and polyfills out there. In fact, I am a co-maintainer of the most popular one. This one is different in a few ways, however:

Works in both Node.js and browsers with minimal amount of differences in code
Ships with both ESM and CommonJS versions
Uses modern APIs such as the fetch() API and Web Streams
Does NOT attempt to be API-compatible with the browser EventSource API:
- Supports async iterator pattern
- Supports any request method (POST, PATCH, DELETE etc)
- Supports setting custom headers
- Supports sending a request body
- Supports configurable reconnection policies
- Supports subscribing to any event (eg if event names are not known)
- Supports subscribing to events named error
- Supports setting initial last event ID

Installation

npm install --save eventsource-client

Supported engines

Node.js >= 18
Chrome >= 63
Safari >= 11.3
Firefox >= 65
Edge >= 79
Deno >= 1.30
Partial: Bun (has issues with unicode)

Basically, any environment that supports:

Usage (async iterator)

import {createEventSource} from 'eventsource-client'

const es = createEventSource({
  url: 'https://my-server.com/sse',

  // your `fetch()` implementation of choice, or `globalThis.fetch` if not set
  fetch: myFetch,
})

let seenMessages = 0
for await (const {data, event, id} of es) {
  console.log('Data: %s', data)
  console.log('Event ID: %s', id) // Note: can be undefined
  console.log('Event: %s', event) // Note: can be undefined

  if (++seenMessages === 10) {
    break
  }
}

// IMPORTANT: EventSource is _not_ closed automatically when breaking out of
// loop. You must manually call `close()` to close the connection.
es.close()

Usage (`onMessage` callback)

import {createEventSource} from 'eventsource-client'

const es = createEventSource({
  url: 'https://my-server.com/sse',

  onMessage: ({data, event, id}) => {
    console.log('Data: %s', data)
    console.log('Event ID: %s', id) // Note: can be undefined
    console.log('Event: %s', event) // Note: can be undefined
  },

  // your `fetch()` implementation of choice, or `globalThis.fetch` if not set
  fetch: myFetch,
})

console.log(es.readyState) // `open`, `closed` or `connecting`
console.log(es.lastEventId)

// Later, to terminate and prevent reconnections:
es.close()

Minimal usage

import {createEventSource} from 'eventsource-client'

const es = createEventSource('https://my-server.com/sse')
for await (const {data} of es) {
  console.log('Data: %s', data)
}