{"id":12667,"library":"websocket-stream","title":"WebSocket Stream Adapter","description":"websocket-stream provides an interface to WebSockets using the Node.js Streams API, allowing developers to pipe data directly to and from a WebSocket connection. It is designed to work seamlessly in both Node.js environments and modern browsers that support WebSockets, making it a versatile tool for real-time applications. The current stable version is 5.5.2, with minor and patch releases occurring periodically, indicating active maintenance. Key differentiators include its adherence to the Node.js Streams API for managing WebSocket data, offering a familiar and composable interface compared to directly manipulating `WebSocket` instances. It integrates well with server-side WebSocket libraries like `ws` and can be used with frameworks such as Express via `express-ws`, streamlining the creation of full-duplex communication channels.","status":"active","version":"5.5.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/maxogden/websocket-stream","tags":["javascript","websocket","websockets","stream","streams","realtime"],"install":[{"cmd":"npm install websocket-stream","lang":"bash","label":"npm"},{"cmd":"yarn add websocket-stream","lang":"bash","label":"yarn"},{"cmd":"pnpm add websocket-stream","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core WebSocket library used for Node.js server-side implementations and client-side communication.","package":"ws","optional":false},{"reason":"Used for integrating websocket-stream with Express.js applications on the server-side, providing an app.ws() route handler.","package":"express-ws","optional":true}],"imports":[{"note":"Primary import for both client and server-side usage. For ESM, use the default import; for CJS, use `require`.","wrong":"const websocket = require('websocket-stream')","symbol":"websocket","correct":"import websocket from 'websocket-stream'"},{"note":"`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.","wrong":"import { createServer } from 'websocket-stream'","symbol":"createServer","correct":"import websocket from 'websocket-stream'; websocket.createServer(...)"},{"note":"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.","wrong":"import { websocketStream } from 'websocket-stream'","symbol":"websocketStream","correct":"import websocketStream from 'websocket-stream/stream'"}],"quickstart":{"code":"import websocket from 'websocket-stream';\nimport { createReadStream, createWriteStream } from 'fs';\n\nconst ws = websocket('ws://echo.websocket.org');\n\n// Pipe stdin to the WebSocket\nprocess.stdin.pipe(ws);\n\n// Pipe WebSocket data to stdout\nws.pipe(process.stdout);\n\n// Example of piping a file to the WebSocket\n// const fileStream = createReadStream('data.txt');\n// fileStream.pipe(ws);\n\n// Example of receiving data from WebSocket and saving to a file\n// const outputFileStream = createWriteStream('received.txt');\n// ws.pipe(outputFileStream);\n\nconsole.log('Connected to ws://echo.websocket.org. Type something and press Enter!');","lang":"javascript","description":"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."},"warnings":[{"fix":"Review 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.","message":"Major 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.","severity":"breaking","affected_versions":">=4.0.0, >=5.0.0"},{"fix":"Explicitly 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.","message":"The `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.","severity":"gotcha","affected_versions":">=3.3.3"},{"fix":"Carefully 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.","message":"Options 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.","severity":"gotcha","affected_versions":">=3.3.3"},{"fix":"Upgrade to `websocket-stream@5.1.2` or higher to ensure the use of modern and safe `Buffer` allocation methods (e.g., `Buffer.from()`).","message":"Older versions might have used deprecated `Buffer` constructors, which can lead to runtime warnings or security issues in newer Node.js environments.","severity":"deprecated","affected_versions":"<5.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"The `createServer` method is a property of the default export. Use `import websocket from 'websocket-stream'; websocket.createServer(...)`.","cause":"Attempting to import `createServer` as a named export from `websocket-stream` in an ESM context, or incorrectly destructuring it from the default import.","error":"TypeError: websocket.createServer is not a function"},{"fix":"Ensure 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.","cause":"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).","error":"Error: WebSocket is not open: readyState 0 (CONNECTING)"},{"fix":"For 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.","cause":"Using `require('websocket-stream')` in a TypeScript or JavaScript file configured for ESM, or directly in a browser environment without a bundler.","error":"ReferenceError: require is not defined in ES module scope"}],"ecosystem":"npm"}