TypeScript icon, indicating that this package has built-in type declarations

1.1.2 • Public • Published

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(e.data == 'close') websocketHeartbeatJs.close();

2.ping & 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: ${e.data}`);
websocketHeartbeatJs.onreconnect = function () {

use script

<script src="./node_modules/websocket-heartbeat-js/dist/index.js"></script>
let websocketHeartbeatJs = new window.WebsocketHeartbeatJs({
    url: 'ws://xxxxxxx'


websocketHeartbeatJs.ws (WebSocket)

This websocketHeartbeatJs.ws is native Websocket instance. If you need more native Websocket features, operate the websocketHeartbeatJs.ws.

websocketHeartbeatJs.ws == WebSocket(websocketHeartbeatJs.opts.url);

websocketHeartbeatJs.opts (Object)

Attribute required type default description
url true string none websocket service address
protocols false string or string[] none new WebSocket(, protocols)
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 any "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) => {
    console.log('msg:', e.data);

websocketHeartbeatJs.onreconnect (function)

websocketHeartbeatJs.onreconnect = (e) => {


demo show



similar package



npm i websocket-heartbeat-js

DownloadsWeekly Downloads






Unpacked Size

17.2 kB

Total Files


Last publish


  • zimv