ws

Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js

weekly downloads145.2M

versionv8.19.0

licenseMIT

categorybackend

HyBiPushRFC-6455WebSocketWebSocketsreal-time

Overview

The ws package is the de facto standard WebSocket implementation for Node.js, providing both client and server capabilities that fully comply with RFC-6455. With over 145 million weekly downloads, it powers real-time communication in countless production applications, from chat systems to live dashboards and multiplayer games.

Unlike browser WebSocket APIs that only support clients, ws enables you to create WebSocket servers directly in Node.js without external dependencies. It passes the rigorous Autobahn test suite and is consistently benchmarked as the fastest pure JavaScript WebSocket library available. The package handles the complexity of the WebSocket protocol—framing, masking, pings/pongs, and connection lifecycle—while exposing a clean event-driven API.

Developers choose ws for its stability, performance, and flexibility. It integrates seamlessly with existing HTTP servers like Express, supports permessage-deflate compression for bandwidth optimization, and provides fine-grained control over connection management. The library is maintained actively, receives regular security patches, and has been battle-tested across diverse production environments for over a decade.

While Node.js v21+ introduced experimental native WebSocket support for clients, ws remains essential for server-side implementations and offers significantly more features, configurability, and production reliability than experimental native APIs.

Quick Start

typescript

import { WebSocketServer } from 'ws';
import http from 'http';

const server = http.createServer();
const wss = new WebSocketServer({ server });

wss.on('connection', (ws, req) => {
  const clientIp = req.socket.remoteAddress;
  console.log(`Client connected from ${clientIp}`);

  ws.on('message', (data, isBinary) => {
    const message = isBinary ? data : data.toString();
    console.log('Received:', message);

    wss.clients.forEach((client) => {
      if (client.readyState === client.OPEN) {
        client.send(`Echo: ${message}`, { binary: isBinary });
      }
    });
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });

  ws.on('close', () => {
    console.log('Client disconnected');
  });

  ws.send(JSON.stringify({ type: 'welcome', timestamp: Date.now() }));
});

server.listen(8080, () => {
  console.log('WebSocket server running on ws://localhost:8080');
});

Use Cases

Real-time chat applications: Build multi-user chat rooms where messages are instantly broadcast to all connected clients. The ws library handles concurrent connections efficiently, allowing you to iterate through connected clients and selectively send messages based on room membership or user permissions.

Live data dashboards: Stream continuously updating metrics, stock prices, or IoT sensor data to web clients without polling. WebSocket's persistent connection reduces latency and server overhead compared to repeated HTTP requests, making ws ideal for applications requiring sub-second data updates.

Collaborative editing tools: Implement operational transformation or CRDT-based collaboration where multiple users edit the same document simultaneously. The bidirectional nature of WebSockets via ws enables low-latency synchronization of cursor positions, text changes, and presence indicators.

Multiplayer game servers: Manage game state synchronization between players with minimal latency. The ws package's performance characteristics and ability to handle binary data (ArrayBuffers, Buffers) make it suitable for transmitting position updates, game actions, and state snapshots efficiently.

Microservice event streaming: Create internal event buses where services push notifications to subscribers in real-time. Use ws to build lightweight pub/sub systems or complement message queues with WebSocket connections for services requiring immediate event delivery without polling overhead.

Pros & Cons

Pros

+Fastest RFC-6455 compliant WebSocket implementation for Node.js with proven performance benchmarks
+Both client and server support in a single package with comprehensive API for connection management and broadcasting
+Mature and stable with 145M+ weekly downloads, extensive production usage, and active maintenance with security updates
+Flexible integration with existing HTTP servers and frameworks like Express, plus support for permessage-deflate compression
+Clean event-driven API with excellent TypeScript definitions and minimal learning curve for developers familiar with Node.js patterns

Cons

−Requires manual implementation of higher-level patterns like rooms, authentication middleware, or automatic reconnection logic
−Permessage-deflate compression disabled by default on servers due to memory/CPU overhead, requiring conscious trade-off decisions
−No built-in fallback mechanisms for environments that block WebSocket connections (unlike Socket.IO or SockJS)
−Security vulnerabilities have been discovered in past versions requiring regular updates and dependency monitoring
−Binary data handling requires explicit buffer management and type checking, adding complexity compared to text-only messaging

Alternatives

socket.iov4.8.3

node.js realtime framework server

backendrealtimeframework

10.2M / week

Comparisons

socket.io vs ws

backend

Install

bash

npm install ws

bash

pnpm add ws

bash

bun add ws

Overview

Quick Start

typescript

import { WebSocketServer } from 'ws';
import http from 'http';

const server = http.createServer();
const wss = new WebSocketServer({ server });

wss.on('connection', (ws, req) => {
  const clientIp = req.socket.remoteAddress;
  console.log(`Client connected from ${clientIp}`);

  ws.on('message', (data, isBinary) => {
    const message = isBinary ? data : data.toString();
    console.log('Received:', message);

    wss.clients.forEach((client) => {
      if (client.readyState === client.OPEN) {
        client.send(`Echo: ${message}`, { binary: isBinary });
      }
    });
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });

  ws.on('close', () => {
    console.log('Client disconnected');
  });

  ws.send(JSON.stringify({ type: 'welcome', timestamp: Date.now() }));
});

server.listen(8080, () => {
  console.log('WebSocket server running on ws://localhost:8080');
});

Use Cases

Pros & Cons

Pros

+Fastest RFC-6455 compliant WebSocket implementation for Node.js with proven performance benchmarks
+Both client and server support in a single package with comprehensive API for connection management and broadcasting
+Mature and stable with 145M+ weekly downloads, extensive production usage, and active maintenance with security updates
+Flexible integration with existing HTTP servers and frameworks like Express, plus support for permessage-deflate compression
+Clean event-driven API with excellent TypeScript definitions and minimal learning curve for developers familiar with Node.js patterns

Cons

−Requires manual implementation of higher-level patterns like rooms, authentication middleware, or automatic reconnection logic
−Permessage-deflate compression disabled by default on servers due to memory/CPU overhead, requiring conscious trade-off decisions
−No built-in fallback mechanisms for environments that block WebSocket connections (unlike Socket.IO or SockJS)
−Security vulnerabilities have been discovered in past versions requiring regular updates and dependency monitoring
−Binary data handling requires explicit buffer management and type checking, adding complexity compared to text-only messaging