isomorphic-ws

library5.0.0jsnpmunverified

Isomorphic WebSocket wrapper that uses the ws library on Node.js and the native WebSocket API in browsers. Version 5.0.0 is the latest stable release, published July 2021. Requires ws as a peer dependency. The API matches the browser WebSocket standard but has notable differences from ws's Node interface (e.g., no Server class, no options constructor argument). Provides TypeScript type declarations. Lightweight and straightforward, but developers must test cross-environment behavior. Active maintenance with infrequent releases.

messaging

npm install isomorphic-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ISOMORPHIC-WS

isomorphic-ws

messagingjavascriptv5.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebSocket

✓ import WebSocket from 'isomorphic-ws'

✗ const WebSocket = require('isomorphic-ws').WebSocket

Package exports a default export; named export is not available in CJS or ESM.

WebSocket

✓ const WebSocket = require('isomorphic-ws')

✗ const { WebSocket } = require('isomorphic-ws')

CJS require returns the default export directly. Using destructured require will result in undefined.

WebSocket types

✓ import type WebSocket from 'isomorphic-ws'

✗ import { WebSocket } from 'isomorphic-ws' (for types)

TypeScript users can import the type separately. The default export is a value, not a namespace.

Creates an isomorphic WebSocket connection to a test server, sends timestamps and measures roundtrip time.

import WebSocket from 'isomorphic-ws'; const ws = new WebSocket('wss://echo.websocket.org/'); ws.onopen = () => { console.log('connected'); ws.send(Date.now()); }; ws.onmessage = (event) => { console.log(`Roundtrip time: ${Date.now() - Number(event.data)} ms`); setTimeout(() => ws.send(Date.now()), 500); }; ws.onclose = () => console.log('disconnected'); ws.onerror = (error) => console.error('WebSocket error:', error);

Debug

Known issues

gotchaws options constructor argument is not supported in browsers

fix

Only use the address and protocols arguments; do not pass options like { perMessageDeflate } when running in browser.

affects: >=0.0.0

gotchaNo Server implementation in browsers; attempting to use ws.Server will fail

fix

Use ws.Server only in Node.js environment; conditionally import server code.

affects: >=0.0.0

gotchaThe native browser WebSocket API does not expose all ws features (e.g., binaryType, compression)

fix

Test your code in both Node and browsers to ensure feature compatibility.

affects: >=0.0.0

breakingVersion 5.0.0 dropped support for older Node versions (requires Node >=10)

fix

Upgrade Node to 10 or later, or continue using 4.x if stuck on older versions.

affects: 5.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ws'

ws is a peer dependency and must be installed separately.

fix

Run 'npm install ws' alongside isomorphic-ws.

TypeError: WebSocket is not a constructor

Incorrect import: using destructured require or import.

fix

Use 'import WebSocket from "isomorphic-ws"' or 'const WebSocket = require("isomorphic-ws")'.

ReferenceError: WebSocket is not defined (in Node)

ws package not installed or not found.

fix

Ensure ws is installed as a dependency: 'npm install ws'.

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/heineiuo/isomorphic-ws ↗

packageisomorphic-ws ↗

homepagehttps://github.com/heineiuo/isomorphic-ws#readme ↗