react-socket-link

A lightweight, TypeScript-first WebSocket library for React featuring hook-based APIs, automatic reconnection with exponential backoff, typed pub/sub messaging, and flexible multi-connection management.

• Named connections — useSubscription('chat', ...), useSend('notifications')
• Static connections (known at startup) and dynamic ones (pattern-based, resolved at runtime)
• Auto-reconnect with exponential backoff and full jitter
• Message queue while disconnected, flushed on reconnect
• Heartbeat / dead-connection detection
• React Strict Mode safe

Installation

npm install react-socket-link

Quick start

1. Wrap your app with WebSocketProvider

import { WebSocketProvider } from 'react-socket-link';

function App() {
  return (
    <WebSocketProvider
      connections={{
        chat: { url: 'wss://api.example.com/chat' },
        notifications: { url: 'wss://api.example.com/notifications' },
      }}
    >
      <YourApp />
    </WebSocketProvider>
  );
}

2. Subscribe to messages in any component

import { useSubscription, useSend } from 'react-socket-link';

function ChatBox() {
  const send = useSend('chat');

  useSubscription('chat', '*', (message) => {
    console.log('received', message);
  });

  return <button onClick={() => send({ type: 'hello', payload: 'world' })}>Send</button>;
}

Typing your messages

Extend BaseMessage with a discriminated union to get exhaustive type checking in subscribers:

import type { BaseMessage } from 'react-socket-link';

type ChatMessage =
  | { type: 'chat';     payload: { user: string; text: string } }
  | { type: 'presence'; payload: { user: string; online: boolean } };

Then pass the type to hooks:

useSubscription<ChatMessage>('chat', 'chat', (msg) => {
  // msg is typed as { type: 'chat'; payload: { user: string; text: string } }
  console.log(msg.payload.text);
});

Using '*' as the event type receives every message as the full union:

useSubscription<ChatMessage>('chat', '*', (msg) => {
  // msg is ChatMessage — switch on msg.type for exhaustive handling
});

Provider

Static connections

Static connections are known at startup. Each key is the name you'll reference from hooks.

<WebSocketProvider
  connections={{
    general:       { url: 'wss://api.example.com/ws?type=general' },
    chat:          { url: 'wss://api.example.com/ws?type=chat' },
    notifications: { url: 'wss://api.example.com/ws?type=notifications', autoConnect: false },
  }}
>
  {children}
</WebSocketProvider>

Dynamic connections

Use the resolve prop for connections whose URLs depend on runtime values (room IDs, document IDs, etc.). It is called the first time a hook requests a name that isn't in the static map.

<WebSocketProvider
  connections={{ general: { url: '...' } }}
  resolve={(name) => {
    if (name.startsWith('room:')) {
      const id = name.slice(5);
      return { url: `wss://api.example.com/rooms/${id}` };
    }
    return null; // not handled — provider will throw a clear error
  }}
>
  {children}
</WebSocketProvider>

Return null or undefined for names your resolver doesn't handle. The provider throws a descriptive error rather than silently creating a broken connection.

Global error handler

Pass onError to capture errors from every connection (static and dynamic) in one place:

<WebSocketProvider
  connections={connections}
  resolve={resolveConnection}
  onError={(name, event) => {
    captureError(event, { tags: { connection: name } });
  }}
>
  {children}
</WebSocketProvider>

The name argument is the connection name ('chat', 'room:42', etc.).

Hooks

useSubscription

Subscribe to messages on a connection. Re-subscribes only when the connection name or message type changes — inline handler functions are safe to pass without causing churn.

useSubscription<ChatMessage>('chat', 'chat', (msg) => {
  console.log(msg.payload.text);
});

// Subscribe to all message types
useSubscription<ChatMessage>('chat', '*', (msg) => {
  switch (msg.type) { ... }
});

useSend

Returns a stable send function. Returns true if sent immediately, false if queued (when queueWhileDisconnected is enabled).

const send = useSend<ChatMessage>('chat');
send({ type: 'chat', payload: { user: 'alice', text: 'hello' } });

useConnectionState

Tracks the connection state as React state — triggers a re-render on each transition.

import { ConnectionState, useConnectionState } from 'react-socket-link';

const state = useConnectionState('chat');
// ConnectionState.CONNECTING | OPEN | CLOSING | CLOSED | RECONNECTING

useWebSocket

Returns the raw WebSocketClient instance. Use this when you need direct access — for example, to set up a per-component error handler:

const client = useWebSocket('chat');

useEffect(() => client.onError((event) => {
  console.error('chat error', event);
}), [client]);

useDynamicConnection

Manages a single dynamic connection that follows an ID. When the ID changes, the previous connection is closed and a new one is opened. On unmount, the active connection is closed automatically.

function Room({ roomId }: { roomId: string | null }) {
  // Returns 'room:42' when roomId is '42', null when roomId is null
  const connectionName = useDynamicConnection('room', roomId);

  useSubscription<RoomMessage>(
    connectionName ?? 'room:_placeholder',
    '*',
    (msg) => { ... },
  );
}

The provider's resolve function must handle the resulting name (room:42).

useCloseClient

Closes and removes a client by name. The next time a hook requests the same name, the client is recreated from config. Useful for explicitly tearing down dynamic connections.

const closeClient = useCloseClient();
closeClient('room:42');

useDynamicConnection handles this automatically on ID change and unmount. Use useCloseClient directly only when you need manual control.

Connection options

All options for WebSocketClientOptions:

| Option | Type | Default | Description | |---|---|---|---| | url | string | — | WebSocket URL (ws:// or wss://) | | protocols | string \| string[] | — | Sub-protocols for the native WebSocket | | autoConnect | boolean | true | Connect immediately on construction | | reconnect | boolean | true | Auto-reconnect on unexpected close | | maxReconnectAttempts | number | Infinity | Give up after this many attempts | | backoff | BackoffStrategy | exponential, capped at 30s | Delay between reconnect attempts | | queueWhileDisconnected | boolean | true | Queue outbound messages while offline | | maxQueueSize | number | 100 | Max queued messages (oldest dropped) | | heartbeat.message | TMessage \| string | { type: 'ping' } | Message to send as a ping | | heartbeat.intervalMs | number | 30000 | Ping interval in ms | | heartbeat.timeoutMs | number | 60000 | Silence threshold before force-reconnect | | serialize | (msg) => string \| ArrayBuffer \| Blob | JSON.stringify | Outbound message serializer | | deserialize | (data) => TMessage \| null | JSON.parse | Inbound message deserializer |

Backoff strategies

Two built-in strategies, or bring your own BackoffStrategy = (attempt: number) => number:

import { exponentialBackoff, fixedBackoff } from 'react-socket-link';

// Exponential with full jitter — prevents thundering herd on server restart
// Formula: random(0, min(cap, base * 2^attempt))
exponentialBackoff(1000, 30_000) // default

// Fixed delay — useful for tests or LAN apps
fixedBackoff(2000)

Framework-agnostic client

WebSocketClient has no React dependency and can be used in any environment:

import { WebSocketClient } from 'react-socket-link';

const client = new WebSocketClient<ChatMessage>({
  url: 'wss://api.example.com/chat',
  reconnect: true,
});

const unsub = client.subscribe('chat', (msg) => {
  console.log(msg.payload.text);
});

client.onStateChange((state) => console.log('state:', state));
client.onError((event) => console.error('error:', event));

client.send({ type: 'chat', payload: { user: 'alice', text: 'hello' } });
client.close();
unsub();

React Strict Mode

The provider is Strict Mode safe. In development, React mounts effects twice (mount → cleanup → remount) to surface bugs. The provider tracks which connections were active when the cleanup ran and reconnects only those on remount — connections configured with autoConnect: false are never prematurely started.