{"id":15610,"library":"eventsource","title":"EventSource Client for Node.js and Browsers","description":"This package provides a WhatWG/W3C compliant EventSource client, enabling applications to consume Server-Sent Events (SSE) in both Node.js and modern browser environments. The current stable version is 4.1.0, with regular updates and major releases approximately every six months, indicating active maintenance. It aims for a minimal implementation closely adhering to the specification, distinguishing itself from alternatives like `eventsource-client` which offer a more flexible API. It supports Node.js versions 20 and higher, along with a wide range of modern browsers, Deno, and Bun, by leveraging standard web APIs like `fetch`, `ReadableStream`, and `TextDecoder`. The library also provides a mechanism to override the `fetch` implementation, offering greater control in diverse runtime environments. TypeScript types are shipped directly with the package, requiring appropriate `tsconfig.json` setup for correct type inference depending on the target environment.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"git://git@github.com/EventSource/eventsource","tags":["javascript","sse","eventsource","server-sent-events","typescript"],"install":[{"cmd":"npm install eventsource","lang":"bash","label":"npm"},{"cmd":"yarn add eventsource","lang":"bash","label":"yarn"},{"cmd":"pnpm add eventsource","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v3.0.0, EventSource is a named export. Prior versions used a default export. The module is primarily ESM-first, requiring bundlers for CJS usage after v3.0.0.","wrong":"import EventSource from 'eventsource'","symbol":"EventSource","correct":"import { EventSource } from 'eventsource'"},{"note":"This type replaced `FetchLikeInit` in v4.0.0 for configuring the fetch operation.","symbol":"EventSourceFetchInit","correct":"import type { EventSourceFetchInit } from 'eventsource'"}],"quickstart":{"code":"import { EventSource } from 'eventsource';\n\n// Replace with your SSE endpoint\nconst sseEndpoint = 'https://my-server.com/sse';\n\nconst es = new EventSource(sseEndpoint);\n\nes.addEventListener('notice', (event) => {\n  console.log('Notice received:', event.data);\n});\n\nes.addEventListener('update', (event) => {\n  console.log('Update received:', event.data);\n});\n\nes.addEventListener('message', (event) => {\n  console.log('Message received:', event.data);\n});\n\nes.addEventListener('error', (err) => {\n  console.error('EventSource error:', err);\n  if (err.code === 401 || err.code === 403) {\n    console.log('Authentication or authorization failed.');\n  }\n});\n\nconsole.log(`Connecting to SSE endpoint: ${sseEndpoint}`);\n\n// Close the connection after 10 seconds to demonstrate clean shutdown\nsetTimeout(() => {\n  console.log('Closing EventSource connection.');\n  es.close();\n}, 10_000);","lang":"typescript","description":"Demonstrates connecting to an SSE endpoint, listening for various event types, handling errors, and explicitly closing the connection."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer. For older Node.js versions, use `eventsource@^3.0.0` or `eventsource@^2.0.0` depending on requirements.","message":"Node.js v18 support has been dropped. The package now requires Node.js v20 or higher.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your TypeScript code to use `EventSourceFetchInit` instead of `FetchLikeInit` for fetch initialization options.","message":"The `FetchLikeInit` TypeScript type has been removed and replaced with `EventSourceFetchInit`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Change your import statements from `import EventSource from 'eventsource'` to `import { EventSource } from 'eventsource'`. If targeting browsers without a bundler, consider using an older major version (2.x).","message":"The `EventSource` module now uses a named export instead of a default export. Also, UMD bundles are no longer provided, requiring a bundler for browser environments.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To customize fetch behavior (e.g., add headers, use proxies, configure HTTPS agents), pass a custom `fetch` function to the `EventSource` constructor's options, wrapping your desired `fetch` implementation.","message":"Direct `headers`, HTTP/HTTPS proxy support, and `https.*` options within the `EventSource` constructor's init dictionary have been removed.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"For browser environments, ensure your `tsconfig.json` includes `\"lib\": [\"dom\"]`. For Node.js, ensure `@types/node` is installed (version 18 or higher) and correctly configured in your `tsconfig.json`.","message":"TypeScript compilation errors ('Cannot find name 'Event'', 'EventTarget'', 'MessageEvent'') occur when `tsconfig.json` is not correctly configured for the target environment.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `\"lib\": [\"dom\"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.","cause":"TypeScript compiler cannot locate the global 'Event' type definition.","error":"error TS2304: Cannot find name 'Event'."},{"fix":"Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `\"lib\": [\"dom\"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.","cause":"TypeScript compiler cannot locate the global 'EventTarget' type definition.","error":"error TS2304: Cannot find name 'EventTarget'."},{"fix":"Configure your `tsconfig.json` to include the appropriate `lib` entry (e.g., `\"lib\": [\"dom\"]` for browsers) or ensure `@types/node` (>=18) is installed for Node.js environments.","cause":"TypeScript compiler cannot locate the global 'MessageEvent' type definition.","error":"error TS2304: Cannot find name 'MessageEvent'."},{"fix":"For versions `>=3.0.0`, use `import { EventSource } from 'eventsource';`. If you must use CommonJS, consider transpiling or using an older major version (2.x) that supported CommonJS default exports directly.","cause":"Attempting to use `EventSource` as a default export or via `require()` in environments where it expects a named ESM export.","error":"TypeError: EventSource is not a constructor (or similar CJS module error)"}],"ecosystem":"npm"}