A polyfill implementing the W3C EventSource (Server-Sent Events) API for browsers that lack native support. Current stable version is 1.0.31. It fills gaps in older browsers like IE 10+ (XDomainRequest for IE 8-9 with limitations), Firefox 3.5+, Chrome 3+, Safari 4+, and Opera 12+. Key differentiators: cross-domain support, custom headers, and configurable last-event-id parameter. The README strongly discourages use ("Please do not use this shitty library!") due to quality concerns, but the package remains actively maintained for legacy compatibility.
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Use named import; the package does not export a default. For CJS, require also works but named export pattern is preferred for ESM compatibility.
import { EventSourcePolyfill } from 'event-source-polyfill'
NativeEventSource is a named export, not default. Use it to detect native support.
import { NativeEventSource } from 'event-source-polyfill'
The library does not automatically set global.EventSource. You must assign it manually if needed for third-party libraries.
import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill';
const EventSource = NativeEventSource || EventSourcePolyfill;
global.EventSource = EventSource;
Demonstrates importing and using EventSourcePolyfill with fallback to native, plus custom headers usage.
import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill';
const EventSource = NativeEventSource || EventSourcePolyfill;
const url = '/events';
const es = new EventSource(url);
es.onmessage = (event) => {
console.log('Received:', event.data);
};
es.onerror = (err) => {
console.error('EventSource error:', err);
};
// Using custom headers (only with EventSourcePolyfill)
if (!NativeEventSource) {
const esWithHeaders = new EventSourcePolyfill(url, {
headers: { 'Authorization': 'Bearer ' + (process.env.TOKEN || '') }
});
esWithHeaders.onmessage = (event) => console.log(event.data);
}
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.