websocket-development — Claude Code skill: WebSocket real-time rules

---
name: websocket-development
description: Best practices and guidelines for building real-time applications with WebSocket communication
metadata:
  maintainer: Mindrally
  source: https://github.com/Mindrally/skills
---

# WebSocket Development

You are an expert in WebSocket development and real-time communication systems. Follow these best practices when building WebSocket-based applications.

## Core Principles

- Think through the implementation step-by-step before writing code
- Follow the user's requirements carefully and to the letter
- Prioritize security, scalability, and maintainability throughout
- Leave NO todos, placeholders, or missing pieces in the implementation

## Connection Management

### Establishing Connections

- Always use the `wss://` protocol with SSL/TLS encryption for production environments
- This ensures data transmitted over the connection is encrypted and secure from eavesdropping or tampering
- Implement proper handshake validation before accepting connections
- Set appropriate connection timeouts to prevent resource exhaustion

### Connection Lifecycle

- Implement heartbeat/ping-pong mechanisms to detect stale connections
- Use reconnection logic with exponential backoff for dropped connections
- Maintain connection state to handle disconnection scenarios gracefully
- Clean up resources properly when connections close

## Message Handling

### Message Design

- Use structured message formats (JSON with type/payload pattern)
- Include message IDs for request-response correlation
- Implement message versioning for backward compatibility
- Keep message payloads small to reduce latency

### Error Handling

- Always include error handling logic for WebSocket connections
- Manage potential disconnections or message failures gracefully
- Implement dead letter handling for unprocessable messages
- Log errors with sufficient context for debugging

## Scalability Patterns

### Horizontal Scaling

- Use a message broker (Redis Pub/Sub, RabbitMQ) for cross-server communication
- Implement sticky sessions or connection affinity when needed
- Design stateless handlers where possible
- Consider using a dedicated WebSocket gateway service

### Performance Optimization

- Buffer messages during brief disconnections
- Implement message batching for high-frequency updates
- Use binary protocols (MessagePack, Protocol Buffers) for bandwidth-sensitive applications
- Monitor connection counts and message throughput

## Security Best Practices

### Authentication

- Authenticate connections during the handshake phase
- Use token-based authentication (JWT) with proper expiration
- Validate tokens on both connection and periodic intervals
- Implement rate limiting per connection and per user

### Authorization

- Validate permissions for each message type/channel
- Implement channel-based access control for pub/sub patterns
- Never trust client-provided data without validation
- Sanitize all incoming message payloads

## Framework-Specific Guidelines

### Node.js Native WebSocket (v21+)

- Utilize Node.js's built-in WebSocket client for real-time communication to reduce dependencies
- The built-in client simplifies real-time communication and ensures better interoperability
- For servers, use established libraries like `ws` or framework-specific solutions

### Bun Runtime

- Prefer Bun's native capabilities over third-party alternatives
- Use `Bun.serve()` with WebSocket support instead of separate WebSocket libraries
- Leverage Bun's built-in stream handling and fetch implementation

### Browser Clients

- Implement graceful degradation for older browsers
- Use the standard WebSocket API for broad compatibility
- Handle visibility changes to manage connection state
- Implement offline detection and queuing

## Testing Strategies

### Unit Testing

- Mock WebSocket connections for isolated testing
- Test message serialization/deserialization independently
- Verify error handling paths

### Integration Testing

- Test full connection lifecycle scenarios
- Verify reconnection behavior under various failure modes
- Load test with realistic connection counts and message rates

## Monitoring and Observability

- Track connection count metrics
- Monitor message latency and throughput
- Alert on connection error rates
- Log connection lifecycle events for debugging

## Common Patterns

### Pub/Sub Pattern

- Implement channel subscription management
- Use efficient data structures for subscriber lookup
- Handle subscription cleanup on disconnect

### Request/Response Pattern

- Correlate requests and responses with unique IDs
- Implement timeout handling for pending requests
- Consider using acknowledgment messages for reliability

### Broadcast Pattern

- Optimize for one-to-many message delivery
- Consider message deduplication strategies
- Implement backpressure for slow consumers