WebSocket Library for Node.js

Common errors

• Cannot find module 'bufferutil'

  cause The optional `bufferutil` binary addon, used for performance, is not installed or failed to compile for your specific Node.js environment.
  fix Install it as an optional dependency: `npm install --save-optional bufferutil`. If compilation fails, ensure you have Python and C++ build tools installed, or use the `WS_NO_BUFFER_UTIL=1` environment variable to disable its use.

• TypeError: WebSocket is not a constructor

  cause Attempting to instantiate `ws.WebSocket` in a web browser environment, where the `ws` package is not designed to run.
  fix In web browsers, use the native `window.WebSocket` constructor. If you see `ReferenceError: WebSocket is not defined`, it's the same root cause – `ws` isn't providing the browser global.

• The requested module 'ws' does not provide an export named WebSocketServer

  cause This typically occurs in an ES Modules context when `import { WebSocketServer } from 'ws'` is used, but the environment or `package.json` configuration is not correctly set up for ESM, or if there's confusion with the default CommonJS export.
  fix Ensure your `package.json` has `"type": "module"`. If still facing issues or sticking with CommonJS, use `const { WebSocketServer } = require('ws');` or `const WebSocket = require('ws'); const wss = new WebSocket.Server();`.

• HTTP/1.1 426 Upgrade Required

  cause A regular HTTP client is attempting to connect to a WebSocket server without performing the correct WebSocket handshake, or the handshake itself is malformed/unsupported.
  fix Ensure your client is initiating a proper WebSocket connection (e.g., `new WebSocket('ws://...')` in a browser or Node.js client) and that the server is correctly configured to handle WebSocket upgrade requests.

Warnings

• breaking The `ws` package is designed exclusively for Node.js environments and does not function directly in web browsers. Attempting to use it in a browser will result in errors.
  Fix: For browser environments, use the native `window.WebSocket` object. If isomorphic code (Node.js and browser compatible) is required, consider using a wrapper like `isomorphic-ws`.
• gotcha `bufferutil` and `utf-8-validate` are optional binary addons that can significantly improve `ws` performance for specific operations. Without them, `ws` will fall back to slower JavaScript implementations.
  Fix: Install them as optional dependencies: `npm install --save-optional bufferutil utf-8-validate`. If you encounter build issues, ensure your system has the necessary C++ compiler tools. They can be explicitly disabled via `WS_NO_BUFFER_UTIL` and `WS_NO_UTF_8_VALIDATE` environment variables.
• breaking A Denial of Service (DoS) vulnerability (CVE-2024-37890) was fixed in `ws` v8.17.1 (and backports to v7.5.10, v6.2.3, v5.2.4). Prior versions could crash if a client sent a request with an excessive number of HTTP headers, exceeding `server.maxHeadersCount`.
  Fix: Upgrade to `ws` v8.17.1 (or the latest patch in your major version line, e.g., 7.5.10, 6.2.3, 5.2.4) or newer immediately to mitigate this vulnerability. Consider configuring `server.maxHeadersCount` in Node.js HTTP servers if exposing them to untrusted clients.
• gotcha `ws` v8.19.0 included a fix for a 'forthcoming breaking change in Node.js core'. Older `ws` versions might encounter compatibility issues with future Node.js releases if not updated.
  Fix: It is recommended to upgrade to `ws` v8.19.0 or newer to ensure continued compatibility and stability with upcoming Node.js versions.
• gotcha When using `ws` with ES Modules (ESM) in Node.js, there can be confusion between the default import (`import WebSocket from 'ws'`) for the client and the named import (`import { WebSocketServer } from 'ws'`) for the server. Some environments or configurations might default to CommonJS behavior, leading to import errors.
  Fix: Ensure your project is configured correctly for ESM (`"type": "module"` in `package.json`) if using `import` statements. Use `import WebSocket from 'ws'` for the client and `import { WebSocketServer } = from 'ws'` for the server. For CommonJS, use `const WebSocket = require('ws')` and `const WebSocketServer = require('ws').Server`.

Install

• npm install ws npm
• yarn add ws yarn
• pnpm add ws pnpm

Imports

• WebSocket
  wrong:

  const WebSocket = require('ws')

  correct:

  import WebSocket from 'ws'

  For client-side WebSocket connections within Node.js, `WebSocket` is the default export. While CommonJS `require` is still supported, ESM imports are generally preferred in modern Node.js environments (v10+).
• WebSocketServer
  wrong:

  const WebSocketServer = require('ws').Server

  correct:

  import { WebSocketServer } from 'ws'

  The WebSocket server constructor is a named export. Directly accessing `.Server` on the default CommonJS import is also common. Incorrectly using `import WebSocketServer from 'ws'` can lead to runtime errors in some ESM contexts.
• PerMessageDeflate

  import { PerMessageDeflate } from 'ws'

  The `PerMessageDeflate` class, used for customizing the permessage-deflate extension, was explicitly exported starting from `ws` v8.20.0.

Quickstart

Demonstrates how to set up a basic `ws` WebSocket server listening on an HTTP port, handle incoming messages, and how to connect to it using a `ws` client, sending and receiving text data.

import { WebSocketServer, WebSocket } from 'ws';
import * as http from 'http';

// Create a simple HTTP server to attach the WebSocket server to
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('WebSocket server is running\n');
});

const wss = new WebSocketServer({ server });

wss.on('connection', function connection(ws) {
  console.log('Client connected');

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

    // Echo the message back to the client
    ws.send(`Echo: ${message}`);
  });

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

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

  ws.send('Welcome to the WebSocket server!');
});

server.listen(8080, () => {
  console.log('HTTP and WebSocket server listening on http://localhost:8080');

  // Example client connecting to the server
  const client = new WebSocket('ws://localhost:8080');

  client.onopen = () => {
    console.log('Client connected to WebSocket server');
    client.send('Hello from client!');
  };

  client.onmessage = (event) => {
    console.log('Client received:', event.data);
    client.close(); // Close after receiving an echo
  };

  client.onerror = (error) => {
    console.error('Client WebSocket error:', error);
  };

  client.onclose = () => {
    console.log('Client disconnected');
    server.close(); // Close the server after client disconnects
  };
});