Need help with websocket-heartbeat-js?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

487 Stars 158 Forks MIT License 72 Commits 3 Opened issues


:hearts: simple and useful

Services available


Need anything else?

Contributors list

# 75,720
59 commits

Build Status DeepScan Grade

websocket-heartbeat-js (中文版README)


The websocket-heartbeat-js is base on WebSocket of browser javascript, whose main purpose is to ensure web client and server connection, and it has a mechanism of heartbeat detection and automatic reconnection. When client device has network outage or server error which causes websocket to disconnect, the program will automatically reconnect until reconnecting is successful again.


When we use the native websocket, if network disconnects, any event function not be executed. So front-end program doesn't know that websocket was disconnected. But if program is now executing WebSocket.send(), browser must discover that message signal is failed, so the onclose function will execute.

Back-end websocket service is likely to happen error, when websocket disconnected that front-end not notice message received. So need to send ping message by timeout. Server return pong message to client when server received ping message. Because received pong message, client know connection normal. If client not received pong message, it is connection abnormal, client will reconnect.

In summary, for solve above two problems. Client should initiative send ping message for check connect status.


1.close websocket connection

If websocket need to disconnect, client must execute WebsocketHeartbeatJs.close(). If server wants to disconnect, it should send a close message to client. When client received close message that it to execute WebsocketHeartbeatJs.close().


websocketHeartbeatJs.onmessage = (e) => {
    if( == 'close') websocketHeartbeatJs.close();
} & pong

Server should to return pong message when the client sends a ping message. Pong message can be of any value. websocket-heartbeat-js will not handle pong message, instead it will only reset heartbeat after receiving any message, as receiving any message means that the connection is normal.



npm install websocket-heartbeat-js


import WebsocketHeartbeatJs from 'websocket-heartbeat-js';
let websocketHeartbeatJs = new WebsocketHeartbeatJs({
    url: 'ws://xxxxxxx'
websocketHeartbeatJs.onopen = function () {
    console.log('connect success');
    websocketHeartbeatJs.send('hello server');
websocketHeartbeatJs.onmessage = function (e) {
    console.log(`onmessage: ${}`);
websocketHeartbeatJs.onreconnect = function () {

use script

let websocketHeartbeatJs = new window.WebsocketHeartbeatJs({
    url: 'ws://xxxxxxx'

API (WebSocket)

This is native Websocket instance. If you need more native Websocket features, operate the == WebSocket(websocketHeartbeatJs.opts.url);

websocketHeartbeatJs.opts (Object)

| Attribute | required | type | default | description | | ------ | ------ | ------ | ------ | ------ | | url | true | string | none | websocket service address | | pingTimeout | false | number | 15000 | A heartbeat is sent every 15 seconds. If any backend message is received, the timer will reset | | pongTimeout | false | number | 10000 | After the Ping message is sent, the connection will be disconnected without receiving the backend message within 10 seconds | | reconnectTimeout | false | number | 2000 | The interval of reconnection | | pingMsg | false | string | "heartbeat" | Ping message value | | repeatLimit | false | number | null | The trial times of reconnection。default: unlimited |

const options = {
    url: 'ws://xxxx',
    pingTimeout: 15000, 
    pongTimeout: 10000, 
    reconnectTimeout: 2000,
    pingMsg: "heartbeat"
let websocketHeartbeatJs = new WebsocketHeartbeatJs(options);

websocketHeartbeatJs.send(msg) (function)

Send the message to the back-end service

websocketHeartbeatJs.send('hello server');

websocketHeartbeatJs.close() (function)

The front end manually disconnects the websocket connection. This method does not trigger reconnection.

hook function and event function

websocketHeartbeatJs.onclose (function)

websocketHeartbeatJs.onclose = () => {
    console.log('connect close');

websocketHeartbeatJs.onerror (function)

websocketHeartbeatJs.onerror = () => {
    console.log('connect onerror');

websocketHeartbeatJs.onopen (function)

websocketHeartbeatJs.onopen = () => {
    console.log('open success');

websocketHeartbeatJs.onmessage (function)

websocketHeartbeatJs.onmessage = (e) => {

websocketHeartbeatJs.onreconnect (function)

websocketHeartbeatJs.onreconnect = (e) => {


demo show



similar package


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.