react-websocket-kit

A high-performance React WebSocket client with channel/event pub-sub routing, heartbeat keep-alive, auto-reconnect with exponential backoff, and UMD/CDN support.

Features

• 🔌 useWebSocket hook — Component-level WebSocket with full lifecycle control
• 📡 Channel & Event Pub/Sub — Subscribe to structured { channel, event, payload } messages
• 🔁 Auto-Reconnect — Exponential backoff with configurable attempts and max delay
• 💓 Heartbeat Keep-Alive — Detect dead connections and self-heal automatically
• 🌐 Shared Connections — <WebSocketProvider> shares a single socket across your component tree
• 📦 Dual Build — ESM (import) and UMD (<script> tag) outputs
• 🏷️ Full TypeScript — Ships .d.ts declarations for every export

Installation

npm / yarn / pnpm

npm install react-websocket-kit
# or
yarn add react-websocket-kit
# or
pnpm add react-websocket-kit

CDN (Script Tag)

<!-- React 18 (peer dependency) -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- React WebSocket Kit -->
<script src="https://unpkg.com/react-websocket-kit/dist/index.umd.cjs"></script>

<script>
  // All exports available on the global namespace:
  const { useWebSocket, WebSocketProvider, useWebSocketEvent, ReadyState } = ReactWebSocketKit;
</script>

Quick Start

1. Basic Hook Usage

Use useWebSocket for a single component-scoped connection:

import { useWebSocket, ReadyState } from 'react-websocket-kit';

function LiveStatus() {
  const { readyState, sendRaw, lastMessage } = useWebSocket('ws://localhost:8080');

  return (
    <div>
      <p>Status: {readyState === ReadyState.OPEN ? '🟢 Connected' : '🔴 Offline'}</p>
      <button onClick={() => sendRaw('Hello Server!')}>Send</button>
      <p>Last message: {lastMessage?.data}</p>
    </div>
  );
}

2. Channel & Event Pub/Sub

All structured messages follow a standard envelope:

{
  "channel": "chat:lobby",
  "event": "new_message",
  "payload": { "sender": "Alice", "text": "Hello!" }
}

Emitting events

const { emit } = useWebSocket('ws://localhost:8080');

// Sends: {"channel":"chat:lobby","event":"new_message","payload":{"text":"Hi"}}
emit('chat:lobby', 'new_message', { text: 'Hi' });

Subscribing to events (imperative)

const { subscribe } = useWebSocket('ws://localhost:8080');

useEffect(() => {
  const unsubscribe = subscribe('chat:lobby', 'new_message', (payload) => {
    console.log(payload.text);
  });
  return unsubscribe;
}, []);

Subscribing to events (declarative hook)

import { useWebSocketEvent } from 'react-websocket-kit';

function ChatMessages() {
  const [messages, setMessages] = useState([]);

  // Auto-subscribes on mount, auto-unsubscribes on unmount
  useWebSocketEvent('chat:lobby', 'new_message', (payload) => {
    setMessages((prev) => [...prev, payload]);
  });

  return (
    <ul>
      {messages.map((m, i) => (
        <li key={i}>{m.sender}: {m.text}</li>
      ))}
    </ul>
  );
}

3. Shared Connection via Provider

Wrap your app in <WebSocketProvider> to share a single socket across all child components:

import { WebSocketProvider, useSharedWebSocket, useWebSocketEvent } from 'react-websocket-kit';

function App() {
  return (
    <WebSocketProvider url="ws://localhost:8080" options={{ heartbeat: true }}>
      <Dashboard />
      <Notifications />
    </WebSocketProvider>
  );
}

function Dashboard() {
  const { emit, readyState } = useSharedWebSocket();
  // emit(), sendRaw(), subscribe() all available here
}

function Notifications() {
  useWebSocketEvent('alerts', 'new_alert', (payload) => {
    alert(payload.message);
  });
}

API Reference

useWebSocket(url, options?)

The core hook. Returns a connection instance.

| Parameter | Type | Description | |---|---|---| | url | string \| () => string \| Promise<string> | WebSocket server URL or async resolver | | options | WebSocketOptions | Configuration (see below) |

WebSocketOptions

| Option | Type | Default | Description | |---|---|---|---| | manual | boolean | false | If true, won't connect on mount — call connect() manually | | reconnect | boolean \| ReconnectOptions | true | Auto-reconnect config (see below) | | heartbeat | boolean \| HeartbeatOptions | false | Keep-alive config (see below) | | queryParams | Record<string, string \| number \| boolean> | — | Appended to the connection URL | | protocols | string \| string[] | — | WebSocket sub-protocols | | onOpen | (event: Event) => void | — | Fires on connection open | | onClose | (event: CloseEvent) => void | — | Fires on connection close | | onMessage | (event: MessageEvent) => void | — | Fires on every raw incoming message | | onError | (event: Event) => void | — | Fires on WebSocket error |

ReconnectOptions

| Option | Type | Default | Description | |---|---|---|---| | attempts | number | Infinity | Max reconnect attempts | | delay | number | 2000 | Initial delay (ms) | | maxDelay | number | 30000 | Maximum delay cap (ms) | | exponential | boolean | true | Use exponential backoff |

HeartbeatOptions

| Option | Type | Default | Description | |---|---|---|---| | message | string \| object | 'ping' | Payload sent as keep-alive | | interval | number | 30000 | How often to ping (ms) | | timeout | number | 10000 | Time to wait for pong before closing (ms) | | pongMessage | string \| object | — | Expected server response to reset timeout |

Return Value (UseWebSocketReturn)

| Property | Type | Description | |---|---|---| | readyState | ReadyState | Current connection state | | lastMessage | MessageEvent \| null | Last raw message event received | | sendRaw(data) | function | Send a raw string or binary payload | | emit(channel, event, payload) | function | Send a structured { channel, event, payload } JSON message | | subscribe(channel, event, cb) | function | Register a listener. Returns an unsubscribe function | | unsubscribe(channel, event, cb) | function | Remove a specific listener | | connect() | function | Manually open/reconnect the connection | | disconnect() | function | Close the connection (prevents auto-reconnect) | | getWebSocket() | function | Access the underlying WebSocket instance |

useWebSocketEvent(channel, event, callback, connection?)

Declarative hook that subscribes to a specific channel and event. Automatically cleans up on unmount.

useWebSocketEvent('orders', 'status_update', (payload) => {
  console.log(`Order ${payload.orderId} is now ${payload.status}`);
});

| Parameter | Type | Description | |---|---|---| | channel | string | Channel name to listen on | | event | string | Event name to listen for | | callback | (payload: T) => void | Handler called with the event payload | | connection | UseWebSocketReturn | (Optional) Custom connection. If omitted, uses nearest <WebSocketProvider> |

<WebSocketProvider>

React context provider that creates and shares a single WebSocket connection.

<WebSocketProvider url="ws://localhost:8080" options={{ heartbeat: true }}>
  {children}
</WebSocketProvider>

| Prop | Type | Description | |---|---|---| | url | string \| () => string \| Promise<string> | WebSocket server URL | | options | WebSocketOptions | Same options as useWebSocket |

useSharedWebSocket()

Access the shared connection created by the nearest <WebSocketProvider>. Returns the same UseWebSocketReturn shape as useWebSocket.

const { emit, readyState, subscribe, disconnect } = useSharedWebSocket();

ReadyState Enum

| Value | Constant | Meaning | |---|---|---| | 0 | ReadyState.CONNECTING | Socket is connecting | | 1 | ReadyState.OPEN | Connection is open and ready | | 2 | ReadyState.CLOSING | Connection is closing | | 3 | ReadyState.CLOSED | Connection is closed | | -1 | ReadyState.UNINSTANTIATED | Hook mounted with manual: true, not yet connected |

Message Protocol

When using emit() and subscribe(), all messages are serialized as JSON with this structure:

interface WebSocketEventMessage<T = any> {
  channel: string;   // e.g. "chat:lobby", "market", "notifications"
  event: string;     // e.g. "new_message", "price_update", "alert"
  payload: T;        // any JSON-serializable data
}

Server-side, parse incoming messages as JSON and route by channel + event. Messages that don't match this structure are still delivered to the onMessage callback and lastMessage — so raw text and binary payloads work seamlessly alongside structured events.

Example: Node.js Echo Server

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (ws) => {
  ws.on('message', (data) => {
    const msg = data.toString();

    // Heartbeat
    if (msg === 'ping') {
      ws.send('pong');
      return;
    }

    // Parse structured message
    try {
      const parsed = JSON.parse(msg);
      const { channel, event, payload } = parsed;

      // Broadcast to all clients
      for (const client of wss.clients) {
        if (client.readyState === 1) {
          client.send(JSON.stringify({ channel, event, payload }));
        }
      }
    } catch {
      // Echo raw messages
      ws.send(`Echo: ${msg}`);
    }
  });
});

CDN Usage Example

A complete standalone HTML page using react-websocket-kit from a CDN:

<!DOCTYPE html>
<html>
<head>
  <title>CDN WebSocket Demo</title>
</head>
<body>
  <div id="root"></div>

  <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
  <script src="https://unpkg.com/react-websocket-kit/dist/index.umd.cjs"></script>

  <script type="text/babel">
    const { WebSocketProvider, useSharedWebSocket, useWebSocketEvent, ReadyState } = ReactWebSocketKit;

    function Chat() {
      const { emit, readyState } = useSharedWebSocket();
      const [messages, setMessages] = React.useState([]);

      useWebSocketEvent('chat', 'message', (payload) => {
        setMessages(prev => [...prev, payload]);
      });

      const send = () => {
        emit('chat', 'message', { text: 'Hello!', sender: 'CDN User' });
      };

      return (
        <div>
          <p>Status: {readyState === ReadyState.OPEN ? 'Connected' : 'Offline'}</p>
          <button onClick={send} disabled={readyState !== ReadyState.OPEN}>Send</button>
          <ul>
            {messages.map((m, i) => <li key={i}>{m.sender}: {m.text}</li>)}
          </ul>
        </div>
      );
    }

    function App() {
      return (
        <WebSocketProvider url="ws://localhost:8080">
          <Chat />
        </WebSocketProvider>
      );
    }

    ReactDOM.createRoot(document.getElementById('root')).render(<App />);
  </script>
</body>
</html>

TypeScript

All types are exported and available:

import type {
  WebSocketOptions,
  WebSocketEventMessage,
  UseWebSocketReturn,
  ReconnectOptions,
  HeartbeatOptions,
  EventListenerCallback,
  WebSocketProviderProps,
} from 'react-websocket-kit';

License

MIT