sse.js is a robust JavaScript library designed as a flexible replacement for the standard `EventSource` API, enabling more control over Server-Sent Events (SSE) streams. Unlike `EventSource`, it supports POST requests and allows custom HTTP headers, making it suitable for authenticated or complex SSE integrations. The library is currently at version 2.8.0 and receives active maintenance, with recent releases focusing on spec compliance, type definition fixes, and enhanced auto-reconnect capabilities. It differentiates itself by providing a comprehensive EventSource polyfill that addresses the limitations of the native API, such as the inability to send payloads or custom headers, while offering features like configurable reconnection logic and exposure of HTTP response details.
npm install sse.jsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to establish an SSE connection using `sse.js` with custom headers, POST requests, and robust auto-reconnect logic. It includes event listeners for 'open', 'message', 'error', and 'abort' events, showing how to handle incoming JSON data and reconnection attempts, all within a TypeScript context. The stream is manually started and closed after a timeout.
Do not use version 2.4.0 in TypeScript projects. Upgrade to v2.4.1 or later to resolve the missing type definitions.
Deploy your SSE server over HTTP/2 or HTTP/3 to mitigate the connection limit, which increases to around 100 simultaneous streams. Alternatively, consider using techniques like sub-domains or reusing connections across tabs if HTTP/1.1 is unavoidable.
Review server-side SSE event formatting and client-side logic, particularly around event IDs, retry delays, and data parsing, to ensure compatibility with the updated specification compliance.
Implement 'keep-alive' messages (e.g., empty comment lines `:\n\n`) from the server every 15-30 seconds to prevent proxy timeouts. Consider using HTTP/2 or HTTP/3 where possible, as they handle streaming more robustly. Advise users encountering issues to check their network or firewall settings.
Ensure `useLastEventId: true` is set in the `SSE` constructor options, especially if using `autoReconnect`, to leverage the `Last-Event-ID` header for seamless stream resumption. Upgrade to v2.3.0 or later for improved `Last-Event-ID` support.
Use a named import for `SSE`: `import { SSE } from 'sse.js';` for ESM or `const { SSE } = require('sse.js');` for CommonJS.If `sse.js` is bundled for browser use and intended to be global, ensure its types are globally declared or accessed as a module. For module-based projects, stick to `import { SSE } from 'sse.js';`. The README shows an async import to attach to `window` for non-module contexts: `(async () => { const { SSE } = await import('./sse.js'); window.SSE = SSE; })();`Verify the `SSE_SERVER_URL` is correct and accessible. Check if the server is running and configured to handle SSE requests (e.g., `Content-Type: text/event-stream`, `Connection: keep-alive`). Also, ensure proper CORS headers are set on the server if the client is on a different origin.
Configure your SSE server to include the `Access-Control-Allow-Origin` header in its response, allowing requests from your client's origin. For example, `res.setHeader('Access-Control-Allow-Origin', 'http://localhost:8080');` or `res.setHeader('Access-Control-Allow-Origin', '*');` for development.No dependency data recorded yet.