Skip to content
Get packs

ws

A Node.js library for building WebSocket clients and servers, with a focus on speed and testing.

GitHub Download 8.22.1
Stars
22.8k
Forks
2.7k
Licence
MIT
Language
JavaScript
Last update
5 days ago
Type
Library

What it is

ws is a WebSocket library for Node.js that lets a server and a client exchange messages over a persistent connection, which is useful for live, two-way communication. It implements the WebSocket protocol (RFC 6455 per its topics) and is described in its README as passing the Autobahn test suite. It is a backend-side tool: the README says it does not work in the browser, where the native WebSocket object should be used instead.

  • Build a WebSocket server that receives and broadcasts messages to connected clients
  • Write a Node.js client that connects to an existing WebSocket endpoint and sends text or binary data
  • Run a WebSocket server alongside an HTTPS server on the same port, routing upgrade requests by path
  • Add client authentication during the upgrade handshake using noServer mode

Great for

  • Node.js developers who need a WebSocket server or a backend WebSocket client
  • Projects that want a small, widely used library with an API documented in doc/ws.md
  • Teams that need a WebSocket server to share one HTTP or HTTPS server with other handlers
  • Developers who want optional compression (permessage-deflate) and are willing to tune it

Not ideal for

  • Browser-only front-end code: the README says the library does not work in the browser, so use the native WebSocket object or a wrapper like isomorphic-ws.
  • Projects that need the permessage-deflate compression on by default on a busy production server: the README notes it adds significant performance and memory cost and warns of Node.js zlib issues under high concurrency.
  • Non-programmers looking for a ready-made app: this is a code library, not an end-user tool.
Step-by-step guide: how to use wsInstall, first run, examples, tips and FAQs
Socket.IO vs ws

How to get it

  1. 1

    Install with a package manager

    You'll need: Node.js (the README mentions support for versions before v18.14.0 only in the context of an optional module; check the package for the current minimum)

    Install ws from npm

    npm install ws

    Optional performance addon

    npm install --save-optional bufferutil
  2. 2

    Run it

    • Install the package with npm install ws
    • Create a file that imports WebSocketServer from 'ws' and starts a server on a port, such as 8080
    • Add a 'connection' handler that listens for 'message' events and calls ws.send
    • Connect with a second script using new WebSocket('ws://...') from the library to test the exchange
  3. 3

    Get the most out of it

    • Set up the bufferutil optional package to speed up masking and unmasking of frame data
    • Use noServer mode with handleUpgrade to share one HTTP or HTTPS server between several WebSocket endpoints
    • Enable perMessageDeflate only when needed and test it under your real workload, as the README advises
    • Use the streams API for piping data through Node.js stream code

Downloads

Source code (.zip)master branch · straight from GitHubRelease 8.22.1Release notes and source

Strengths

  • The README describes it as passing the Autobahn test suite for both server and client
  • Simple, Node.js-style API with examples for text, binary, streams, and shared HTTP servers
  • Optional performance addon (bufferutil) and compression settings are documented

Trade-offs

  • Does not run in browsers; front-end code needs a different WebSocket API
  • Compression is off by default on the server and carries a noted performance and memory cost
  • The README provided is truncated, so some details (such as the full options list) require reading the separate API docs

How it compares

ProjectStarsTypeLevelUpdatedBest for
ws (this)22.8kLibrarybeginner5 days agoNode.js developers who need a WebSocket server or a backend WebSocket client
socket.io63.2kLibraryintermediate1 months agoDevelopers building live chat or real-time notifications in JavaScript or TypeScript
http-proxy-middleware11.1kLibraryintermediate5 days agoNode.js developers running an Express, Connect, or Next.js dev server who need to forward /api requests to a backend
nuxt61kLibraryintermediate4 days agoDevelopers who already know Vue.js and want a structured full-stack setup
echo32.8kLibraryintermediate6 days agoGo developers building REST APIs or backend services
feathers15.3kLibraryintermediate5 days agoJavaScript or TypeScript developers building a web API

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.