{"id":18321,"library":"event-source-polyfill","title":"EventSource Polyfill","description":"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.","status":"active","version":"1.0.31","language":"javascript","source_language":"en","source_url":"git://github.com/Yaffle/EventSource","tags":["javascript","sse","server sent events","eventsource","event-source","polyfill"],"install":[{"cmd":"npm install event-source-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add event-source-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add event-source-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Use named import; the package does not export a default. For CJS, require also works but named export pattern is preferred for ESM compatibility.","wrong":"const EventSourcePolyfill = require('event-source-polyfill')","symbol":"EventSourcePolyfill","correct":"import { EventSourcePolyfill } from 'event-source-polyfill'"},{"note":"NativeEventSource is a named export, not default. Use it to detect native support.","wrong":"import NativeEventSource from 'event-source-polyfill'","symbol":"NativeEventSource","correct":"import { NativeEventSource } from 'event-source-polyfill'"},{"note":"The library does not automatically set global.EventSource. You must assign it manually if needed for third-party libraries.","wrong":"global.EventSource = require('event-source-polyfill');","symbol":"EventSource (global)","correct":"import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill';\nconst EventSource = NativeEventSource || EventSourcePolyfill;\nglobal.EventSource = EventSource;"}],"quickstart":{"code":"import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill';\n\nconst EventSource = NativeEventSource || EventSourcePolyfill;\nconst url = '/events';\nconst es = new EventSource(url);\n\nes.onmessage = (event) => {\n  console.log('Received:', event.data);\n};\n\nes.onerror = (err) => {\n  console.error('EventSource error:', err);\n};\n\n// Using custom headers (only with EventSourcePolyfill)\nif (!NativeEventSource) {\n  const esWithHeaders = new EventSourcePolyfill(url, {\n    headers: { 'Authorization': 'Bearer ' + (process.env.TOKEN || '') }\n  });\n  esWithHeaders.onmessage = (event) => console.log(event.data);\n}","lang":"typescript","description":"Demonstrates importing and using EventSourcePolyfill with fallback to native, plus custom headers usage."},"warnings":[{"fix":"Consider using alternative libraries like 'eventsource' or 'fetch-event-source' which may be more reliable.","message":"The library's README explicitly says 'Please do not use this shitty library!' indicating significant quality concerns.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure server adds 2KB of padding at the beginning of SSE responses for IE 8-9 compatibility.","message":"In IE 8-9, XDomainRequest is used, requiring 2KB padding at the start of the stream and not supporting cookies or client certificates.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Set custom 'lastEventIdQueryParameterName' option to match server expectations.","message":"The polyfill uses a query parameter 'lastEventId' by default for Last-Event-ID, which may conflict with server configurations.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add logic to pad chunks on server side for Android Browser support, or avoid targeting this browser.","message":"For Android Browser, 4KB padding after every chunk is required, but the polyfill does not handle this automatically.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use import { NativeEventSource, EventSourcePolyfill } from 'event-source-polyfill'; const EventSource = NativeEventSource || EventSourcePolyfill;","cause":"Importing incorrectly without setting global property or using in unsupported browser without polyfill.","error":"Uncaught ReferenceError: EventSource is not defined"},{"fix":"Run 'npm install event-source-polyfill' and ensure import path matches (no trailing slash).","cause":"Package not installed or path incorrect.","error":"Module not found: Can't resolve 'event-source-polyfill'"},{"fix":"Use import { EventSourcePolyfill } from 'event-source-polyfill' (named import).","cause":"Importing as default instead of named export.","error":"TypeError: EventSourcePolyfill is not a constructor"},{"fix":"Use import 'event-source-polyfill' (side-effect import) or ensure named imports are used.","cause":"Webpack tree-shaking removes side-effect import if not used.","error":"The polyfill stopped working after bundling with webpack"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}