Registry / messaging / websocket-heartbeat-js

websocket-heartbeat-js

library1.1.3jsnpmunverified

WebSocket heartbeat and auto-reconnection library for browser JavaScript. Version 1.1.3 is the latest stable release, with infrequent updates. Automatically sends ping messages to detect connection status and reconnects on failure. Differentiates from native WebSocket by handling network outages and server errors that would otherwise go undetected, using a heartbeat mechanism with configurable intervals and reconnection attempts.

messaging

npm install websocket-heartbeat-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-HEARTBEA

websocket-heartbeat-js

messagingjavascriptv1.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WebsocketHeartbeatJs

✓ import WebsocketHeartbeatJs from 'websocket-heartbeat-js'

✗ const { WebsocketHeartbeatJs } = require('websocket-heartbeat-js')

Default export only; named import is incorrect. TypeScript types are included.

WebsocketHeartbeatJs (script tag)

✓ <script src="./node_modules/websocket-heartbeat-js/dist/index.js"></script>

✗ <script src="websocket-heartbeat-js"></script>

For browser script tag, include the full path to dist/index.js; exposes global window.WebsocketHeartbeatJs.

Options interface

✓ import type { Options } from 'websocket-heartbeat-js'

✗ import { Options } from 'websocket-heartbeat-js'

Options is a TypeScript interface, use type import for isolated declarations.

Creates a websocket heartbeat instance with custom options and event handlers for open, message, close, and reconnect.

import WebsocketHeartbeatJs from 'websocket-heartbeat-js'; const ws = new WebsocketHeartbeatJs({ url: 'wss://echo.websocket.org', pingTimeout: 60000, pongTimeout: 10000, reconnectTimeout: 2000, pingMsg: 'heartbeat' }); ws.onopen = () => { console.log('Connected'); ws.send('Hello server'); }; ws.onmessage = (e) => { console.log('Message:', e.data); }; ws.onclose = () => { console.log('Disconnected'); }; ws.onreconnect = () => { console.log('Reconnecting...'); };

Debug

Known issues

gotchaAuto-reconnect will trigger on any close event (including intentional close via backend). If server sends a close message, you must call close() manually to avoid infinite reconnect loop.

fix

Handle server close messages in onmessage: if (e.data === 'close') ws.close();

affects: >=1.0.0

gotchaThe library does not automatically detect if the connection is already open before sending. Sending before onopen may fail silently.

fix

Always wait for onopen event before calling send().

affects: >=1.0.0

gotchaThe pingMsg option defaults to 'heartbeat' but is not sent as a binary or specific protocol; ensure server expects plain text.

fix

Set pingMsg to match your server's expected ping format, e.g., {type: 'ping'} as JSON string.

affects: >=1.0.0

breakingWhen using with TypeScript, the constructor options type is not fully exported as a named type; you must rely on inference or inline types.

fix

Manually define options interface or upgrade to v1.2.0+ (if available). In v1.1.3, use 'typeof WebsocketHeartbeatJsOptions' as a workaround.

affects: <1.2.0

Errors

Common errors & fixes

Cannot find name 'WebsocketHeartbeatJs'

Using named import instead of default import in TypeScript.

fix

Change to: import WebsocketHeartbeatJs from 'websocket-heartbeat-js'

WebsocketHeartbeatJs is not a constructor

Trying to call require without default property in CommonJS.

fix

Use const WebsocketHeartbeatJs = require('websocket-heartbeat-js').default or use import statement.

ws://xxx: connection refused

Using ws:// with HTTPS page or incorrect URL.

fix

Use wss:// for secure connections or ensure URL matches protocol (ws for HTTP, wss for HTTPS).

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/zimv/websocket-heartbeat-js ↗

packagewebsocket-heartbeat-js ↗

homepagehttps://github.com/zimv/websocket-heartbeat-js#readme ↗