Registry / http-networking / event-source-polyfill

event-source-polyfill

library1.0.31jsnpmunverified

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.

http-networking web-framework

npm install event-source-polyfill

github ↗package ↗

INSTALL

IMPORT

SIG · EVENT-SOURCE-POLYF

event-source-polyfill

http-networkingjavascriptv1.0.31

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.

EventSourcePolyfill

✓ import { EventSourcePolyfill } from 'event-source-polyfill'

✗ const EventSourcePolyfill = require('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

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

✗ import NativeEventSource from 'event-source-polyfill'

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

EventSource (global)

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

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

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

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

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

breakingIn 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaFor 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.

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught ReferenceError: EventSource is not defined

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;

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

Package not installed or path incorrect.

fix

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

TypeError: EventSourcePolyfill is not a constructor

Importing as default instead of named export.

fix

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

The polyfill stopped working after bundling with webpack

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.

Upgrade

Version history

1.0.31latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

OpenAI (training)

Resources

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

packagehttps://www.npmjs.com/package/event-source-polyfill ↗