Get native WebSocket in browsers, or ws in Node.js.

Help you writing WebSocket libraries targeting both browsers and Node.js.

• Difference between isomorphic-ws
• Install
• API
  • Note on TypeScript typing
  • Note on event handler properties
• Usage
  • Force to use ws
• Development
  • Install dependencies
  • Testing
  • Coverage
• License

isomorphic-ws relies on bundlers (like Webpack) to choose between native implementation and ws package. It's not useful when not using a bundler.

This package detects whether there is a native WebSocket implementation, and fallback to ws if not.

npm install @yume-chan/fallback-websocket

ws is a peer dependency, you need to install it separately for Node.js.

npm install ws

export default WebSocket: typeof WebSocket;

export connect(url: string): Promise<WebSocket>;

The exported object always has native WebSocket's type, to use fields added by ws, import WebSocket from ws and cast the object to that.

The onXXX event handler properties in ws are implemented strangely. Setting these properties multiple times will add multiple handlers, instead of overwriting the previous value as browsers do. Use addEventListener/removeEventListener when possible.

import WebSocket from "@yume-chan/fallback-websocket";

// do something useful with WebSocket

Or use the connect() utility function, which returns a Promise that resolves to a connected WebSocket object.

import { connect } from "@yume-chan/fallback-websocket";

try {
  const connection = await connect("ws://localhost:80");
} catch (e) {
  // handle connection exception.
}

In some cases (e.g. running tests in Electron), you might want to use ws even if there is a native implementation.

You can set the FORCE_WS environment variable to achieve this.

This project uses pnpm (GitHub) to manage dependency packages.

pnpm i

You may also use npm, but the lockfile may become out of sync.

npm test

npm run coverage

MIT