Skip to main content

useWebSocket Hook

React hook for WebSocket connection management with automatic reconnection, heartbeat, and message handling.

Overview​

The useWebSocket hook provides comprehensive WebSocket connection management:

  • Automatic connection establishment
  • Configurable reconnection with exponential backoff
  • Heartbeat ping/pong for connection health
  • Message type routing to store actions
  • Toast notifications for critical events
  • Connection status tracking
graph TD
    A[useWebSocket] --> B[WebSocket Connection]
    A --> C[State Management]
    A --> D[Heartbeat System]
    A --> E[Reconnection Logic]
    
    B --> F[onopen]
    B --> G[onmessage]
    B --> H[onerror]
    B --> I[onclose]
    
    G --> J[Message Router]
    J --> K[camera_update]
    J --> L[weather_update]
    J --> M[aqi_update]
    J --> N[accident_alert]
    J --> O[pattern_change]
    
    K --> P[Traffic Store]
    L --> P
    M --> P
    N --> P
    O --> P

Hook Signature​

interface WebSocketConfig {
  url: string;
  reconnectInterval?: number;     // Default: 3000ms
  maxReconnectAttempts?: number;  // Default: Infinity
  heartbeatInterval?: number;     // Default: 10000ms
}

interface WebSocketState {
  connected: boolean;
  connecting: boolean;
  error: Error | null;
  reconnectCount: number;
  lastMessage: WebSocketMessage | null;
}

const useWebSocket = (config: WebSocketConfig): WebSocketState;

Usage​

import { useWebSocket } from '../hooks/useWebSocket';

function TrafficMonitor() {
    const { connected, connecting, error, reconnectCount, lastMessage } = useWebSocket({
        url: 'ws://localhost:5000',
        reconnectInterval: 5000,
        maxReconnectAttempts: 10,
        heartbeatInterval: 10000
    });

    return (
        <div>
            <ConnectionStatus connected={connected} reconnectCount={reconnectCount} />
            {error && <ErrorMessage error={error} />}
        </div>
    );
}

Features​

Automatic Reconnection​

  • Exponential backoff starting from reconnectInterval
  • Maximum delay capped at 30 seconds
  • Configurable max attempts (default: infinite)
const getReconnectDelay = useCallback(() => {
    const baseDelay = reconnectInterval;
    const maxDelay = 30000;
    return Math.min(baseDelay * Math.pow(2, reconnectAttemptsRef.current), maxDelay);
}, [reconnectInterval]);

Heartbeat System​

  • Periodic ping messages to detect stale connections
  • Configurable interval (default: 10 seconds)
  • Automatic restart on reconnection

Message Routing​

Handles different message types and updates Zustand store:

Message TypeStore ActionDescription
initialMultiple settersInitial data snapshot
camera_updatesetCamerasCamera status changes
weather_updatesetWeatherWeather observations
aqi_updatesetAirQualityAir quality readings
new_accidentaddAccidentNew accident detected
pattern_changesetPatternsTraffic pattern updates

Notifications​

Critical events trigger toast notifications:

  • Accident alerts (high priority)
  • AQI warnings (moderate priority)
  • Connection status changes

State Values​

PropertyTypeDescription
connectedbooleanTrue when connection is open
connectingbooleanTrue during connection attempt
errorError | nullLast connection error
reconnectCountnumberNumber of reconnection attempts
lastMessageWebSocketMessage | nullMost recent message received

Dependencies​

  • react@^18.2: useEffect, useRef, useState, useCallback
  • useTrafficStore: Zustand store for state updates
  • useNotification: Toast notification context
  • WebSocketMessage type from ../types

Best Practices​

  1. Single Instance: Use one WebSocket connection per app
  2. Cleanup: Hook handles cleanup on unmount
  3. Error Handling: Always display connection status to users
  4. Reconnection: Configure based on network conditions

See Also​