websocket-integration

Overview

Provides complete guidance and code for integrating native WebSockets or Socket.io into web apps, including reconnection with exponential backoff, message envelope format, React hook for lifecycle management, server-side setup (Node/ws or Socket.io), error handling, and authentication patterns for real-time features.

When to Use This Skill

• Adding live chat, notifications, presence indicators, collaborative editing, or live data dashboards.
• The user mentions "real-time", "WebSocket", "live updates", "push", or "socket".

Prerequisites

• Backend that can run a WebSocket server (Node.js, Deno, or cloud service like Pusher, Ably, Supabase Realtime).
• Frontend framework (React, vanilla, etc.).
• For production: load balancer that supports WebSocket upgrade (Nginx, ALB, etc.).

Steps

1. Choose transport: Native WebSocket (lightweight) vs Socket.io (more features, fallback).
2. Define message protocol (JSON envelope):

   { "type": "chat.message", "payload": {...}, "id": "uuid", "timestamp": "..." }

3. Client implementation:
   • Connection, onopen, onmessage, onerror, onclose.
   • Reconnection logic with backoff (max 5 attempts, then show "reconnecting" UI).
   • Heartbeat / ping-pong for keepalive.
4. React hook (useWebSocket): manages connection, auto-reconnect, typed message handlers.
5. Server side: auth on connection (JWT in query or subprotocol), room management, broadcast.
6. Security: validate all incoming messages, rate limit, authenticate every connection.
7. Output: full hook, example chat component, server route, deployment notes.

Examples

Complete useWebSocket.ts hook, a simple chat UI, and a minimal Node + ws server example are provided.

Edge Cases & Error Handling

• Network drops: exponential backoff + user notification.
• Auth expiration: refresh token and reconnect.
• Large messages: chunk or use binary when appropriate.
• Browser tab sleep: handle visibilitychange to pause/reconnect.

Verification

1. Open two browser tabs — messages appear in real time.
2. Kill the server — client shows reconnecting UI and recovers when server restarts.
3. Check browser console for clean connection lifecycle.
4. Success: Real-time features work reliably with graceful degradation.

References

• MDN WebSocket API
• Socket.io Docs
• ws library (Node)