EventSource Polyfill

1.0.31 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Uncaught ReferenceError: EventSource is not defined ↓

cause Importing incorrectly without setting global property or using in unsupported browser without polyfill.

fix

Use import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill'; const EventSource = NativeEventSource || EventSourcePolyfill;

error Module not found: Can't resolve 'event-source-polyfill' ↓

cause Package not installed or path incorrect.

fix

Run 'npm install event-source-polyfill' and ensure import path matches (no trailing slash).

error TypeError: EventSourcePolyfill is not a constructor ↓

cause Importing as default instead of named export.

fix

Use import { EventSourcePolyfill } from 'event-source-polyfill' (named import).

error The polyfill stopped working after bundling with webpack ↓

cause Webpack tree-shaking removes side-effect import if not used.

fix

Use import 'event-source-polyfill' (side-effect import) or ensure named imports are used.

Warnings

gotcha The library's README explicitly says 'Please do not use this shitty library!' indicating significant quality concerns. ↓

fix Consider using alternative libraries like 'eventsource' or 'fetch-event-source' which may be more reliable.

breaking In IE 8-9, XDomainRequest is used, requiring 2KB padding at the start of the stream and not supporting cookies or client certificates. ↓

fix Ensure server adds 2KB of padding at the beginning of SSE responses for IE 8-9 compatibility.

gotcha The polyfill uses a query parameter 'lastEventId' by default for Last-Event-ID, which may conflict with server configurations. ↓

fix Set custom 'lastEventIdQueryParameterName' option to match server expectations.

gotcha For Android Browser, 4KB padding after every chunk is required, but the polyfill does not handle this automatically. ↓

fix Add logic to pad chunks on server side for Android Browser support, or avoid targeting this browser.

Install

npm install event-source-polyfill

yarn add event-source-polyfill

pnpm add event-source-polyfill

Imports

EventSourcePolyfill
wrong
```
const EventSourcePolyfill = require('event-source-polyfill')
```
correct
```
import { EventSourcePolyfill } from 'event-source-polyfill'
```
Use named import; the package does not export a default. For CJS, require also works but named export pattern is preferred for ESM compatibility.

NativeEventSource

wrong

import NativeEventSource from 'event-source-polyfill'

correct

import { NativeEventSource } from 'event-source-polyfill'

NativeEventSource is a named export, not default. Use it to detect native support.

EventSource (global)

wrong

global.EventSource = require('event-source-polyfill');

correct

import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill';
const EventSource = NativeEventSource || EventSourcePolyfill;
global.EventSource = EventSource;

The library does not automatically set global.EventSource. You must assign it manually if needed for third-party libraries.

Quickstart

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);
}