What is sse-runtime?

This library fills gaps in the browser's built-in way of receiving a continuous stream of updates from a server. That built-in mechanism, called EventSource, has a well-known set of problems: it cannot send an authorization header, so it cannot be used with protected APIs that require a token. The data it delivers is untyped, meaning code that reads it has no idea what shape the data will be. Its reconnection behavior cannot be configured. And when a user opens the same page in multiple tabs, each tab opens its own separate connection to the server. sse-runtime replaces EventSource with a fetch-based implementation that addresses each of these problems. It sends custom headers including authorization tokens, and supports a hook that can refresh an expired token and retry automatically when a 401 response arrives. Event types and their data shapes are declared once, and the library enforces those types throughout so that handler code knows exactly what it is receiving. Reconnection uses a jittered delay that increases after each failure, with a configurable maximum number of retries and a way to classify specific error codes differently. For the multi-tab problem, it uses browser coordination tools to share a single real connection across all tabs showing the same page, with automatic handoff if the coordinating tab closes. The library is split into four packages. The core package has no framework dependency and can be used in any JavaScript environment. A React package wraps the core in a hook that connects when a component mounts and disconnects when it unmounts, keeping event handlers current without tearing down the connection. A React Native package provides lifecycle helpers for mobile apps. A devtools package adds a panel for inspecting live connections and event logs during development. Browser support requires fetch, ReadableStream, AbortController, and TextDecoder, which are available in all modern browsers. The multi-tab coordination feature additionally requires BroadcastChannel and the Web Locks API, and falls back to independent per-tab connections when those are not available. The project is MIT licensed.