isomorphic-ws

What is isomorphic-ws?

The isomorphic-ws npm package provides a WebSocket client that works both in the browser and on the server (Node.js). It is designed to offer a consistent WebSocket API so that developers can write code that is agnostic to the environment in which it runs. This is particularly useful for building isomorphic JavaScript applications that can run on both the client-side and server-side without modification.

What are isomorphic-ws's main functionalities?

Creating WebSocket connections

This feature allows you to create WebSocket connections to a server. The code sample demonstrates how to establish a connection, and handle open, message, and close events.

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

const ws = new WebSocket('ws://www.host.com/path');

ws.onopen = function () {
  console.log('WebSocket is open now.');
};

ws.onmessage = function (event) {
  console.log('Received message: ' + event.data);
};

ws.onclose = function () {
  console.log('WebSocket is closed now.');
};

Sending messages through WebSocket

This feature allows you to send messages to the server over the WebSocket connection. The code sample shows how to send a message to the server once the WebSocket connection is established and open.

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

const ws = new WebSocket('ws://www.host.com/path');

ws.onopen = function () {
  ws.send('Hello Server!');
};

Receiving messages from WebSocket

This feature allows you to receive messages from the server over the WebSocket connection. The code sample demonstrates how to listen for messages from the server and log them to the console.

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

const ws = new WebSocket('ws://www.host.com/path');

ws.onmessage = function (event) {
  console.log('Received message: ' + event.data);
};

Other packages similar to isomorphic-ws

ws

The 'ws' package is a popular WebSocket library for Node.js. Unlike isomorphic-ws, it is not designed to work in the browser environment. It is a robust and well-maintained library that offers a wide range of features including binary data support, extensions, and permessage-deflate compression.

socket.io-client

The 'socket.io-client' package is the client-side library of Socket.IO, which enables real-time bidirectional event-based communication. It is more feature-rich than isomorphic-ws, providing features like auto-reconnection, event broadcasting, and rooms. However, it requires a Socket.IO server to work with, whereas isomorphic-ws can connect to any standard WebSocket server.

websocket

The 'websocket' package provides both client and server implementations of the WebSocket protocol. It is similar to isomorphic-ws in that it can be used in both Node.js and browser environments. However, it offers a more complex API and additional features like WebSocket server implementation, which isomorphic-ws does not provide.

README

isomorphic-ws

Isomorphic implementation of WebSocket.

It uses:

• ws on Node
• global.WebSocket in browsers

Limitations

Before using this module you should know that ws is not perfectly API compatible with WebSocket, you should always test your code against both Node and browsers.

Some major differences:

• no Server implementation in browsers
• no support for the constructor options argument in browsers

Usage

You need to install both this package and ws:

> npm i isomorphic-ws ws

Then just require this package:

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

const ws = new WebSocket('wss://echo.websocket.org/');

ws.onopen = function open() {
  console.log('connected');
  ws.send(Date.now());
};

ws.onclose = function close() {
  console.log('disconnected');
};

ws.onmessage = function incoming(data) {
  console.log(`Roundtrip time: ${Date.now() - data.data} ms`);

  setTimeout(function timeout() {
    ws.send(Date.now());
  }, 500);
};

License

MIT

Changelog

5.0.0 (June 27, 2022)

• Changed browser to es modules (@guillemcordoba in #20)