react-smart-websocket

Smart WebSocket hooks for React with visibility-aware reconnection and multi-connection management.

Features

• Zero dependencies — built on the native browser WebSocket API
• Visibility-aware — automatically pauses when the tab is hidden, reconnects when visible
• Resilient reconnection — exponential backoff with a stability timer to prevent infinite retries
• Multi-connection manager — manage multiple named WebSocket connections from a single provider
• Render isolation — per-connection contexts ensure a message on one connection never re-renders consumers of another
• Heartbeat — optional ping/pong keepalive
• Full TypeScript support — generic message types throughout
• Debug mode — structured logging behind a flag, zero cost when off

---

Installation

npm install react-smart-websocket

---

Quick start

Single connection

import { useCustomWebSocket } from 'react-smart-websocket';

function Chat() {
  const { sendJsonMessage, lastJsonMessage, isConnected } = useCustomWebSocket(
    'wss://example.com/chat',
    { debug: true }
  );

  return (
    <button disabled={!isConnected} onClick={() => sendJsonMessage({ text: 'Hello' })}>
      Send
    </button>
  );
}

Multiple connections

import { WebSocketManagerProvider, useWebSocket } from 'react-smart-websocket';

const connections = [
  { id: 'chat', baseUrl: 'wss://example.com/chat', initialEnabled: true },
  { id: 'notifications', baseUrl: 'wss://example.com/notifications', initialEnabled: true },
];

function App() {
  return (
    <WebSocketManagerProvider connections={connections}>
      <Chat />
      <Notifications />
    </WebSocketManagerProvider>
  );
}

function Chat() {
  const { sendJsonMessage, lastJsonMessage, isConnected } = useWebSocket('chat');
  // ...
}

function Notifications() {
  const { lastJsonMessage } = useWebSocket('notifications');
  // ...
}

---

API

useCustomWebSocket(url, options?, initialEnabled?)

The core low-level hook.

Parameter	Type	Default	Description
url	string | null	—	WebSocket URL. Pass null to skip connecting.
options	CustomWebSocketOptions	{}	Hook options (see below).
initialEnabled	boolean	true	Whether to connect immediately on mount.

Options

Option	Type	Default	Description
debug	boolean	false	Enable structured console logging.
enableHeartbeat	boolean	false	Send ping/pong every 10s, close on 20s timeout.
pauseOnHidden	boolean	true	Close the socket when the tab becomes hidden.
reconnectOnVisible	boolean	true	Reconnect when the tab becomes visible again.
enableReconnect	boolean	true	Reconnect automatically on unexpected close.
onOpen	() => void	—	Called when the connection opens.
onClose	(event?) => void	—	Called when the connection closes.
onError	(error) => void	—	Called on error.
onMessage	(message) => void	—	Called on every incoming message.

Returns

Property	Type	Description
sendMessage	(message: string) => void	Send a raw string message.
sendJsonMessage	(object: T) => void	Serialize and send a JSON message.
lastMessage	MessageEvent | null	The most recent message event.
lastJsonMessage	T | null	The most recent parsed JSON message.
messageHistory	MessageEvent[]	Last 50 messages.
readyState	ReadyState	Current connection state.
connectionStatus	string	Human-readable connection status.
isConnected	boolean	true when open, enabled, and not paused.
getWebSocket	() => WebSocket | null	Access the underlying socket.
debugInfo	object	Internal state snapshot for debugging.
forceReconnect	() => void	Close and immediately reconnect.
disconnect	() => void	Manually close and disable reconnection.
enable	() => void	Enable the connection (connects if a URL is set).
disable	() => void	Disable and close the connection.
isEnabled	boolean	Whether the connection is currently enabled.

---

WebSocketManagerProvider

Wrap your app (or a subtree) to manage multiple named connections.

<WebSocketManagerProvider connections={WebSocketConfig[]}>
  {children}
</WebSocketManagerProvider>

WebSocketConfig

Property	Type	Default	Description
id	string	—	Unique identifier for this connection.
baseUrl	string | null	—	WebSocket base URL.
initialQueryParams	Record<string, string | number | boolean>	{}	Initial query parameters appended to the URL.
initialEnabled	boolean	false	Whether to connect immediately.
options	CustomWebSocketOptions	{}	Hook options (same as useCustomWebSocket).

---

useWebSocket(id)

Read a named connection inside the provider tree.

const { lastJsonMessage, sendJsonMessage, isConnected } = useWebSocket<MyMessage>('chat');

Throws if the id is not registered in the provider.

---

useWebSocketManager()

Monitor all active connections. Re-renders when any connection changes.

const { connections, getConnection } = useWebSocketManager();

---

ReadyState

enum ReadyState {
  UNINSTANTIATED = -1,
  CONNECTING     = 0,
  OPEN           = 1,
  CLOSING        = 2,
  CLOSED         = 3,
}

---

License

MIT