Introduction

Liveflux turns a live connection — WebSocket, Phoenix Channels, or any transport you give it an adapter for — into declarative, typed UI state. It is protocol-agnostic (via adapters) and framework-agnostic (via bindings), so the same engine drives a React app over plain WebSocket, Phoenix Channels, or whatever transport your backend speaks.

The problem

A realtime feature looks small until you ship it. The moment a socket is involved you end up hand-rolling the same plumbing every time:

• Connection lifecycle — connect, detect drops, reconnect with backoff, and re-subscribe on every reopen without losing or duplicating data.
• Multiplexing + dedup — one socket, many subscriptions; identical subscriptions should fold once, not open N sockets.
• Cache glue — turning a raw event stream into the shape a component actually renders (a log, a keyed list, the latest value, an aggregate).
• Backpressure — not blowing up the send buffer when a large active set is replayed over a slow link.
• Tear-free reads — reading changing external state from React without visual tearing under concurrent rendering.

Liveflux is the layer that owns all of that, behind a small typed surface.

Architecture

Liveflux is split into an engine, adapters, and bindings:

• Engine (@liveflux/core) — the LivefluxClient composes a connection manager, a subscription registry (multiplexing + ref-counted dedup), and per-subscription stores. This is the entire public surface; everything else is an implementation detail.
• Adapters — one per wire protocol. An adapter implements the StreamAdapter contract: connect / disconnect / subscribe / unsubscribe, plus optional heartbeat and resume. It normalizes inbound frames into a transport-neutral NormalizedEvent ({ channel, event, payload }) and encodes outbound control frames. The backend's language is irrelevant.
• Bindings — one per UI framework. The React binding exposes useStream and useConnection, reading the core's stores through useSyncExternalStore for tear-free updates.

UI framework  ──  binding        ──  core engine        ──  adapter        ──  your backend
(React)           @liveflux/react     @liveflux/core         @liveflux/ws        (any language)
                  useStream           LivefluxClient         @liveflux/phoenix

Packages

Next