ws-heartbeat

library1.3.0jsnpmunverified

Lightweight heartbeat/ping-pong library for WebSocket connections, compatible with both server-side (ws library) and browser-side WebSocket. Version 1.3.0 provides a simple API to detect dead connections and maintain active WebSocket sessions. Differentiates from manual ping/pong implementations by handling intervals, timeouts, and automatic cleanup. No native WebSocket ping frames required, works with any message format. Low dependency footprint.

messaging

npm install ws-heartbeat

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WS-HEARTBEAT

ws-heartbeat

messagingjavascriptv1.3.0

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.

setWsHeartbeat

✓ import { setWsHeartbeat } from 'ws-heartbeat/client'

✗ import { setWsHeartbeat } from 'ws-heartbeat'

Client-side module is in 'ws-heartbeat/client'. Importing from root will not include the function.

setWsHeartbeat

✓ import { setWsHeartbeat } from 'ws-heartbeat/server'

✗ import { setWsHeartbeat } from 'ws-heartbeat'

Server-side module is in 'ws-heartbeat/server'. Root export does not contain setWsHeartbeat.

setWsHeartbeat

✓ const { setWsHeartbeat } = require('ws-heartbeat/client')

✗ const setWsHeartbeat = require('ws-heartbeat').setWsHeartbeat

CommonJS require must use the specific subpath; the root package has no default export.

Shows client and server setup: client sends ping, server responds with pong, both have timeout handling.

import { setWsHeartbeat } from 'ws-heartbeat/client'; import WebSocket from 'ws'; const ws = new WebSocket('ws://localhost:8080'); setWsHeartbeat(ws, '{"kind":"ping"}', { pingTimeout: 30000, pingInterval: 10000 }); // Server side import { setWsHeartbeat } from 'ws-heartbeat/server'; import { WebSocketServer } from 'ws'; const wss = new WebSocketServer({ port: 8080 }); setWsHeartbeat(wss, (ws, data, binary) => { if (data === '{"kind":"ping"}') { ws.send('{"kind":"pong"}'); } }, 30000);

Debug

Known issues

gotchaThe client-side setWsHeartbeat expects a raw WebSocket instance, not a ws WebSocket when running in browser. Ensure you pass the correct object if transpiling for browser.

fix

Use browser native WebSocket constructor (window.WebSocket) and not the 'ws' library when targeting browser.

affects: >=1.0.0

gotchaThe server-side setWsHeartbeat modifies the WebSocketServer to track clients. If you call it after starting the server, existing connections won't be monitored. Always call before server starts accepting connections.

fix

Call setWsHeartbeat immediately after creating the WebSocketServer, before adding event listeners or starting the server.

affects: >=1.0.0

gotchaThe ping message must be a string. Passing a Buffer or ArrayBuffer will cause type mismatches in the server callback's data parameter.

fix

Ensure the first argument of setWsHeartbeat on the client side is a string (e.g., JSON.stringify).

affects: >=1.0.0

deprecatedThe library's original version (0.x) used a different API with exported objects. Version 1.0+ changed to named exports from subpaths.

fix

Update imports to use 'ws-heartbeat/client' or 'ws-heartbeat/server' as shown in documentation.

affects: <1.0.0

Errors

Common errors & fixes

Cannot find module 'ws-heartbeat' or its corresponding type declarations.

Importing from root instead of subpath (client/server).

fix

Import from 'ws-heartbeat/client' (browser) or 'ws-heartbeat/server' (Node).

TypeError: ws.send is not a function

Passing a raw WebSocket instance instead of a ws.WebSocket on server side, or vice versa on client.

fix

Ensure client uses browser WebSocket (or wrappers) and server uses ws.WebSocket from 'ws' package.

setWsHeartbeat is not a function

Importing the wrong export or using require without proper subpath.

fix

Use correct import: import { setWsHeartbeat } from 'ws-heartbeat/client' (client) or 'ws-heartbeat/server' (server).

Upgrade

Version history

1.3.0latest on npm

Audit

Dependencies

wsoptionalpeer dependency for server-side heartbeat; required only if using the server module

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/plantain-00/ws-heartbeat ↗

packagews-heartbeat ↗

homepagehttps://github.com/plantain-00/ws-heartbeat#readme ↗