isows

library1.0.7jsnpmunverified

Isomorphic WebSocket implementation that works consistently across Node.js, Bun, Deno, and modern browsers. Version 1.0.7 provides a drop-in replacement for the native WebSocket API, using the 'ws' package on Node.js and the native implementation elsewhere. It is actively maintained by the wevm team (known for viem and wagmi). Unlike raw 'ws', isows provides a universal interface without bundler plugins. It is ESM-only and ships TypeScript definitions. Release cadence is infrequent, focused on stability.

storage

npm install isows

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ISOWS

isows

storagejavascriptv1.0.7

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 'isows'

✗ import WebSocket from 'isows'

Named export only; no default export.

WebSocket (in Node.js with require)

✓ const { WebSocket } = require('isows')

✗ const WebSocket = require('isows')

CommonJS destructured require.

CloseEvent

✓ import { CloseEvent } from 'isows'

✗ import { CloseEvent } from 'ws'

Exported for TypeScript type safety; use from isows, not ws directly.

Creates a WebSocket connection to an echo server, sends a message, and logs the response.

import { WebSocket } from 'isows' const ws = new WebSocket('wss://echo.websocket.org') ws.onopen = () => { console.log('connected') ws.send('Hello, world!') } ws.onmessage = (event) => { console.log('Received:', event.data) ws.close() } ws.onclose = (event) => { console.log('Disconnected:', event.code, event.reason) } ws.onerror = (error) => { console.error('WebSocket error:', error) }

Debug

Known issues

breakingisows is ESM-only since v1.0.0 and does not provide a CommonJS bundle.

fix

Use dynamic import() or set type: module in package.json if using Node.js with require.

affects: >=1.0.0

deprecatedThe global WebSocket from 'ws' may be polyfilled; isows always uses its own import.

fix

Always import WebSocket from 'isows' rather than relying on global.

affects: >=1.0.0

gotchaThe 'ws' package must be installed as a peer dependency in Node.js; the package will not work without it.

fix

Install 'ws' alongside isows: npm install isows ws

affects: >=1.0.0

gotchaIn React Native or other non-standard environments, the native WebSocket may be used, which has subtle differences in event timing and binary data handling.

fix

Test thoroughly on target platforms; consider polyfilling with 'react-native-websocket' if needed.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'isows'

Missing dependency; isows not installed or not in node_modules.

fix

Run npm install isows ws

TypeError: WebSocket is not a constructor

Incorrect import — using default import instead of named import.

fix

Use import { WebSocket } from 'isows' instead of import WebSocket from 'isows'

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/isows/index.js not supported

Using CommonJS require with an ESM-only package.

fix

Convert to ESM (type: module) or use dynamic import: const { WebSocket } = await import('isows')

Module not found: Can't resolve 'ws' in '/path/to/project'

Missing peer dependency 'ws'.

fix

Run npm install ws

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

wsrequiredRequired peer dependency for Node.js environments; isows uses it as the underlying WebSocket implementation.

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/wevm/isows ↗

packageisows ↗

homepagehttps://github.com/wevm/isows#readme ↗