WS WebSocket client wrapper to automatically reconnect lost or disconnected connections.


202.2.0a year ago4 years agoMinified + gzip package size for @oznu/ws-connect in KB


WS Connect

WS Connect is a wrapper for the ws WebSocket client for Node.js that will automatically reconnect lost or disconnected WebSocket connections transparently.

This module is for Node.js 10+ only and will not work in the browser. The server implementation must respond to ping messages as required by the WebSocket spec.


npm install @oznu/ws-connect



const { WebSocket } = require('@oznu/ws-connect')

// establish new websocket connection
const socket = new WebSocket('ws://')

// send message to server
socket.send('some message')

// send json to server
socket.sendJson({hello: 'world'})

// listen for messages from server
socket.on('message', (msg) => {

// listen for json from server
socket.on('json', (data) => {

// emitted each time the websocket connection is established
socket.on('open', () => {
  console.log('Websocket Connection Established')

// emitted each time the websocket connection disconnects
socket.on('close', () => {
  console.log('Websocket Connection Closed')

// listen for websocket status events, connect and disconnect events, errors, etc.
socket.on('websocket-status', (status) => {

Class WebSocket

This class represents a WebSocket. It extends the EventEmitter.

new WebSocket(address, [options])

  • address {String} The URL to which to connect.
    • reconnectInterval {Number} The interval in milliseconds between connection attempts. Default 5000.
    • pingInterval {Number} The interval in milliseconds that the client should ping the server. Default 10000.
    • pingFailureLimit {Number} The number of failed pings before a reconnection is attempted. Default 2.
    • beforeConnect {Promise} A function that returns a promise that is to be called before (re)connecting to the server.
    • protocols {String|Array} The list of subprotocols.
    • options {Object} The ws client connection options. See docs.


The original ws client connection.

socket.send(data[, callback])

  • data {Any} The data to send.
  • callback {Function} An optional callback which is invoked when data is written out.

socket.sendJson(data[, callback])

The same as socket.send except the data will be JSON.stringified before being sent.


Closes the WebSocket connection and halts reconnection attempts.

Event: 'message'

  • data {String|Buffer|ArrayBuffer|Buffer[]}

Emitted when a message is received from the server.

Event: 'json'

Emitted when a json data is received from the server.

Event: 'open'

Emitted when the connection is established

Event: 'close'

  • code {Number}
  • reason {String}

Emitted when the connection is closed. code is a numeric value indicating the status code explaining why the connection has been closed. reason is a human-readable string explaining why the connection has been closed.

Event: 'websocket-status'

  • message {String}

Emits human-readable messages regarding the status of the WebSocket connection such as disconnect and reconnecting events, ping timeouts, and errors. Useful for debugging.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.