{"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,"search_vec":"'-9':38 '1.0.31':24 '10':33 '12':49 '3':44 '3.5':42 '4':46 '8':37 'activ':85 'api':13 'browser':15,30 'chrome':43 'compat':89 'concern':80 'configur':59 'cross':53 'cross-domain':52 'current':20 'custom':56 'differenti':51 'discourag':68 'domain':54 'due':77 'event':12,62,94,97 'event-sourc':96 'eventsourc':1,8,95 'fill':26 'firefox':41 'gap':27 'header':57 'id':63 'ie':32,36 'implement':5 'javascript':90 'key':50 'lack':17 'last':61 'last-event-id':60 'legaci':88 'librari':76 'like':31 'limit':40 'maintain':86 'nativ':18 'older':29 'opera':48 'packag':83 'paramet':64 'pleas':70 'polyfil':2,4,99 'qualiti':79 'readm':66 'remain':84 'safari':45 'sent':11,93 'server':10,92 'server-s':9 'shitti':75 'sourc':98 'sse':91 'stabl':21 'strong':67 'support':19,55 'use':69,73 'version':22 'w3c':7 'xdomainrequest':34","created_at":"2026-04-25T07:37:37.413785+00:00","updated_at":"2026-04-25T07:37:37.413785+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Yaffle/EventSource","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/event-source-polyfill","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-24","install_tag":null}}