Wondering what’s next for npm?Check out our public roadmap! »

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

    1.0.13 • Public • Published

    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(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
    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) => {
        console.log('msg:', e.data);

    websocketHeartbeatJs.onreconnect (function)

    websocketHeartbeatJs.onreconnect = (e) => {


    demo show



    similar package



    npm i websocket-heartbeat-js

    DownloadsWeekly Downloads






    Unpacked Size

    18.1 kB

    Total Files


    Last publish


    • avatar