ws

ws is the de facto standard WebSocket implementation for Node.js, providing both client and server APIs that closely mirror the browser’s native WebSocket interface. It implements the full HyBi 07-17 WebSocket protocol drafts (RFC 6455), including the permessage-deflate compression extension, and is validated against the Autobahn test suite for both client and server conformance.

Because it has no required runtime dependencies and exposes low-level primitives like its own Sender and Receiver classes, ws is frequently used both directly by application developers building real-time features and as the underlying transport inside higher-level libraries (Socket.IO, engine.io, and many others) across the Node.js ecosystem.

What You Get

• A WebSocket client class with an API modeled closely on the browser’s native WebSocket, including send, close, event handlers, and an EventTarget-compatible mode
• A WebSocketServer class supporting standalone listening, attachment to existing HTTP/S servers, and manual noServer upgrade handling for routing multiple WebSocket endpoints
• Built-in support for the permessage-deflate compression extension with fine-grained tuning options (window bits, memory level, context takeover)
• Optional native addons (bufferutil, utf-8-validate) that are auto-detected and used to accelerate frame masking/unmasking and UTF-8 validation
• A Node.js streams-compatible duplex wrapper (createWebSocketStream) for piping WebSocket data through the standard streams API
• Broadcast-friendly server APIs (wss.clients) for iterating and messaging all connected clients

Common Use Cases

• Building real-time chat, notification, or collaborative editing backends that push data to connected clients over a single persistent connection
• Implementing low-latency game or trading-data servers where full-duplex, low-overhead messaging outperforms polling-based HTTP
• Acting as the transport layer underneath higher-level realtime frameworks (Socket.IO, engine.io) or custom RPC-over-WebSocket protocols
• Proxying or bridging WebSocket traffic in gateways and API servers that need to multiplex several WebSocket endpoints behind one HTTP server

Under The Hood

Architecture: ws separates concerns cleanly across lib/: websocket.js implements the client-facing WebSocket state machine (connecting, opening, handshake, close negotiation) as an EventEmitter; websocket-server.js implements WebSocketServer, handling HTTP upgrade requests, subprotocol/extension negotiation, and client bookkeeping; and the actual wire protocol is split into sender.js (frame construction, masking, optional deflate) and receiver.js (a Writable stream implemented as an explicit state machine — GET_INFO, GET_PAYLOAD_LENGTH_16/64, GET_MASK, GET_DATA, INFLATING, DEFER_EVENT — that incrementally parses HyBi frames off the incoming socket). permessage-deflate.js implements the negotiated compression extension on top of Node’s zlib, and stream.js adapts a WebSocket into a Node.js Duplex for standard streams interop. index.js composes all of these into the single exported WebSocket class with static properties attached (Server, Receiver, Sender, createWebSocketStream).

Tech Stack: Pure JavaScript targeting Node.js >=10, with zero required runtime dependencies — bufferutil and utf-8-validate are declared only as optional peer dependencies that are dynamically required if present, accelerating masking/unmasking and UTF-8 validation with native addons while falling back to pure-JS implementations otherwise. The package ships dual entry points (index.js for CommonJS require, wrapper.mjs for ESM import, browser.js as a browser-safe stub) declared via the exports map in package.json. Development tooling is ESLint 10 + Prettier for linting/formatting and Mocha + nyc for testing and coverage.

Code Quality: The test suite is extensive — 12 dedicated *.test.js files under test/ covering the receiver state machine, sender, permessage-deflate, extension negotiation, subprotocol parsing, buffer utilities, validation, the WebSocket stream wrapper, and both client and server behavior, plus a separate websocket.integration.js and Autobahn conformance runners (autobahn.js, autobahn-server.js) for full protocol-compliance testing. Source files are consistently documented with JSDoc comments on every exported class and method, private state uses a _-prefixed convention, and internal-only cross-module state uses Symbol keys (kWebSocket, kStatusCode, etc.) to avoid polluting public APIs — a deliberate, disciplined approach to encapsulation for a library operating this close to the wire.

API Design: The client API is intentionally shaped to match the browser’s native WebSocket (new WebSocket(url), .send(), .on('message', ...), readyState constants), which minimizes the learning curve for anyone who has used WebSockets in a browser and enables isomorphic wrapper packages. The 739-line doc/ws.md reference documents every constructor option, event, and method in detail, and the README leads with copy-pasteable examples for the most common scenarios (simple client, simple server, external HTTP server, multi-endpoint routing, authentication, broadcast, round-trip time, streams). Getting a minimal client or server running takes only a few lines of code with no required configuration.