Registry / http-networking / eventsource

eventsource

library1.1.1jsnpmunverified

This package provides a WhatWG/W3C compliant EventSource client, enabling applications to consume Server-Sent Events (SSE) in both Node.js and modern browser environments. The current stable version is 4.1.0, with regular updates and major releases approximately every six months, indicating active maintenance. It aims for a minimal implementation closely adhering to the specification, distinguishing itself from alternatives like `eventsource-client` which offer a more flexible API. It supports Node.js versions 20 and higher, along with a wide range of modern browsers, Deno, and Bun, by leveraging standard web APIs like `fetch`, `ReadableStream`, and `TextDecoder`. The library also provides a mechanism to override the `fetch` implementation, offering greater control in diverse runtime environments. TypeScript types are shipped directly with the package, requiring appropriate `tsconfig.json` setup for correct type inference depending on the target environment.

http-networking web-framework serialization

npm install eventsource

github ↗package ↗

INSTALL

IMPORT

SIG · EVENTSOURCE

eventsource

http-networkingjavascriptv1.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

EventSource

✓ import { EventSource } from 'eventsource'

✗ import EventSource from 'eventsource'

Since v3.0.0, EventSource is a named export. Prior versions used a default export. The module is primarily ESM-first, requiring bundlers for CJS usage after v3.0.0.

EventSourceFetchInit

✓ import type { EventSourceFetchInit } from 'eventsource'

This type replaced `FetchLikeInit` in v4.0.0 for configuring the fetch operation.

Demonstrates connecting to an SSE endpoint, listening for various event types, handling errors, and explicitly closing the connection.

import { EventSource } from 'eventsource'; // Replace with your SSE endpoint const sseEndpoint = 'https://my-server.com/sse'; const es = new EventSource(sseEndpoint); es.addEventListener('notice', (event) => { console.log('Notice received:', event.data); }); es.addEventListener('update', (event) => { console.log('Update received:', event.data); }); es.addEventListener('message', (event) => { console.log('Message received:', event.data); }); es.addEventListener('error', (err) => { console.error('EventSource error:', err); if (err.code === 401 || err.code === 403) { console.log('Authentication or authorization failed.'); } }); console.log(`Connecting to SSE endpoint: ${sseEndpoint}`); // Close the connection after 10 seconds to demonstrate clean shutdown setTimeout(() => { console.log('Closing EventSource connection.'); es.close(); }, 10_000);

Debug

Known issues

breakingNode.js v18 support has been dropped. The package now requires Node.js v20 or higher.

fix

Upgrade your Node.js environment to version 20 or newer. For older Node.js versions, use `eventsource@^3.0.0` or `eventsource@^2.0.0` depending on requirements.

affects: >=4.0.0

breakingThe `FetchLikeInit` TypeScript type has been removed and replaced with `EventSourceFetchInit`.

fix

Update your TypeScript code to use `EventSourceFetchInit` instead of `FetchLikeInit` for fetch initialization options.

affects: >=4.0.0

breakingThe `EventSource` module now uses a named export instead of a default export. Also, UMD bundles are no longer provided, requiring a bundler for browser environments.

fix

Change your import statements from `import EventSource from 'eventsource'` to `import { EventSource } from 'eventsource'`. If targeting browsers without a bundler, consider using an older major version (2.x).

affects: >=3.0.0

breakingDirect `headers`, HTTP/HTTPS proxy support, and `https.*` options within the `EventSource` constructor's init dictionary have been removed.

fix

To customize fetch behavior (e.g., add headers, use proxies, configure HTTPS agents), pass a custom `fetch` function to the `EventSource` constructor's options, wrapping your desired `fetch` implementation.

affects: >=3.0.0

gotchaTypeScript compilation errors ('Cannot find name 'Event'', 'EventTarget'', 'MessageEvent'') occur when `tsconfig.json` is not correctly configured for the target environment.

fix

For browser environments, ensure your `tsconfig.json` includes `"lib": ["dom"]`. For Node.js, ensure `@types/node` is installed (version 18 or higher) and correctly configured in your `tsconfig.json`.

affects: >=3.0.0

Errors

Common errors & fixes

error TS2304: Cannot find name 'Event'.

TypeScript compiler cannot locate the global 'Event' type definition.

fix

Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `"lib": ["dom"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.

error TS2304: Cannot find name 'EventTarget'.

TypeScript compiler cannot locate the global 'EventTarget' type definition.

fix

Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `"lib": ["dom"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.

error TS2304: Cannot find name 'MessageEvent'.

TypeScript compiler cannot locate the global 'MessageEvent' type definition.

fix

Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `"lib": ["dom"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.

TypeError: EventSource is not a constructor (or similar CJS module error)

Attempting to use `EventSource` as a default export or via `require()` in environments where it expects a named ESM export.

fix

For versions `>=3.0.0`, use `import { EventSource } from 'eventsource';`. If you must use CommonJS, consider transpiling or using an older major version (2.x) that supported CommonJS default exports directly.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/EventSource/eventsource ↗

packagehttps://www.npmjs.com/package/eventsource ↗