Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
websocket
✓ import websocket from 'websocket-stream'
✗ const websocket = require('websocket-stream')
Primary import for both client and server-side usage. For ESM, use the default import; for CJS, use `require`.
createServer
✓ import websocket from 'websocket-stream'; websocket.createServer(...)
✗ import { createServer } from 'websocket-stream'
`createServer` is a property of the default export, not a named export. It is used to create a WebSocket server compatible with Node.js streams.
websocketStream
✓ import websocketStream from 'websocket-stream/stream'
✗ import { websocketStream } from 'websocket-stream'
This specific import path (`websocket-stream/stream`) is used when integrating with `express-ws` to convert a raw `ws` instance into a `websocket-stream` instance.
This quickstart demonstrates basic client-side usage, piping standard input to a WebSocket and piping received data to standard output, highlighting its duplex stream capabilities.
import websocket from 'websocket-stream';
import { createReadStream, createWriteStream } from 'fs';
const ws = websocket('ws://echo.websocket.org');
// Pipe stdin to the WebSocket
process.stdin.pipe(ws);
// Pipe WebSocket data to stdout
ws.pipe(process.stdout);
// Example of piping a file to the WebSocket
// const fileStream = createReadStream('data.txt');
// fileStream.pipe(ws);
// Example of receiving data from WebSocket and saving to a file
// const outputFileStream = createWriteStream('received.txt');
// ws.pipe(outputFileStream);
console.log('Connected to ws://echo.websocket.org. Type something and press Enter!');
Debug
Known issues
breakingMajor version updates (v4.0.0, v5.0.0) updated the underlying `ws` dependency, which might introduce breaking changes from `ws` itself, such as API changes or different behaviors in message handling and options.fixReview the changelog for `ws` (versions 2.0.0 and 3.0.0 respectively) for any breaking changes that might affect your application logic or server configuration. Update configurations and code accordingly.
affects: >=4.0.0, >=5.0.0
gotchaThe `perMessageDeflate` option default value differs between client (true) and server (false), and this option is ignored by browser clients. This can lead to unexpected compression behavior or performance issues if not explicitly configured consistently.fixExplicitly set `perMessageDeflate: false` on both the client and server if you aim for the best throughput, especially for large, frequent messages, as recommended in the documentation. For browser clients, ensure server-side configuration dictates the compression behavior.
affects: >=3.3.3
gotchaOptions for `websocket-stream` vary between browser and Node.js environments. Options like `browserBufferSize` and `browserBufferTimeout` are specific to browser clients and have no effect in Node.js.fixCarefully review the documentation for each option and understand its applicability. Implement conditional logic or separate configuration files if your application targets both browser and Node.js environments with different requirements.
affects: >=3.3.3
deprecatedOlder versions might have used deprecated `Buffer` constructors, which can lead to runtime warnings or security issues in newer Node.js environments.fixUpgrade to `websocket-stream@5.1.2` or higher to ensure the use of modern and safe `Buffer` allocation methods (e.g., `Buffer.from()`).
affects: <5.1.2
Errors
Common errors & fixes
TypeError: websocket.createServer is not a function
Attempting to import `createServer` as a named export from `websocket-stream` in an ESM context, or incorrectly destructuring it from the default import.
fixThe `createServer` method is a property of the default export. Use `import websocket from 'websocket-stream'; websocket.createServer(...)`.
Error: WebSocket is not open: readyState 0 (CONNECTING)
Attempting to write to the WebSocket stream before the connection is fully established. The stream is in `CONNECTING` state (readyState 0) and not yet `OPEN` (readyState 1).
fixEnsure you wait for the WebSocket connection to be open before piping data. You can listen for the `open` event on `ws.socket` or the `ready` event on the stream itself if provided by an abstraction layer, or simply ensure your stream pipeline starts after connection is established.
ReferenceError: require is not defined in ES module scope
Using `require('websocket-stream')` in a TypeScript or JavaScript file configured for ESM, or directly in a browser environment without a bundler.
fixFor ESM projects, use `import websocket from 'websocket-stream';`. If targeting browsers, ensure you are using a bundler like Browserify or Webpack that handles CommonJS modules for client-side code.
Audit
Dependencies
wsrequiredCore WebSocket library used for Node.js server-side implementations and client-side communication.
express-wsoptionalUsed for integrating websocket-stream with Express.js applications on the server-side, providing an app.ws() route handler.