{"id":49766,"library":"ws-heartbeat","title":"ws-heartbeat","description":"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.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/plantain-00/ws-heartbeat","tags":["javascript"],"install":[{"cmd":"npm install ws-heartbeat","lang":"bash","label":"npm"},{"cmd":"yarn add ws-heartbeat","lang":"bash","label":"yarn"},{"cmd":"pnpm add ws-heartbeat","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency for server-side heartbeat; required only if using the server module","package":"ws","optional":true}],"imports":[{"note":"Client-side module is in 'ws-heartbeat/client'. Importing from root will not include the function.","wrong":"import { setWsHeartbeat } from 'ws-heartbeat'","symbol":"setWsHeartbeat","correct":"import { setWsHeartbeat } from 'ws-heartbeat/client'"},{"note":"Server-side module is in 'ws-heartbeat/server'. Root export does not contain setWsHeartbeat.","wrong":"import { setWsHeartbeat } from 'ws-heartbeat'","symbol":"setWsHeartbeat","correct":"import { setWsHeartbeat } from 'ws-heartbeat/server'"},{"note":"CommonJS require must use the specific subpath; the root package has no default export.","wrong":"const setWsHeartbeat = require('ws-heartbeat').setWsHeartbeat","symbol":"setWsHeartbeat","correct":"const { setWsHeartbeat } = require('ws-heartbeat/client')"}],"quickstart":{"code":"import { setWsHeartbeat } from 'ws-heartbeat/client';\nimport WebSocket from 'ws';\n\nconst ws = new WebSocket('ws://localhost:8080');\nsetWsHeartbeat(ws, '{\"kind\":\"ping\"}', {\n  pingTimeout: 30000,\n  pingInterval: 10000\n});\n\n// Server side\nimport { setWsHeartbeat } from 'ws-heartbeat/server';\nimport { WebSocketServer } from 'ws';\n\nconst wss = new WebSocketServer({ port: 8080 });\nsetWsHeartbeat(wss, (ws, data, binary) => {\n  if (data === '{\"kind\":\"ping\"}') {\n    ws.send('{\"kind\":\"pong\"}');\n  }\n}, 30000);","lang":"typescript","description":"Shows client and server setup: client sends ping, server responds with pong, both have timeout handling."},"warnings":[{"fix":"Use browser native WebSocket constructor (window.WebSocket) and not the 'ws' library when targeting browser.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Call setWsHeartbeat immediately after creating the WebSocketServer, before adding event listeners or starting the server.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the first argument of setWsHeartbeat on the client side is a string (e.g., JSON.stringify).","message":"The ping message must be a string. Passing a Buffer or ArrayBuffer will cause type mismatches in the server callback's data parameter.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update imports to use 'ws-heartbeat/client' or 'ws-heartbeat/server' as shown in documentation.","message":"The library's original version (0.x) used a different API with exported objects. Version 1.0+ changed to named exports from subpaths.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"search_vec":"'1.3.0':24 'activ':35 'api':28 'automat':48 'browser':20 'browser-sid':19 'cleanup':49 'compat':10 'connect':9,32 'dead':31 'depend':62 'detect':30 'differenti':38 'footprint':63 'format':60 'frame':54 'handl':44 'heartbeat':3 'heartbeat/ping-pong':5 'implement':42 'interv':45 'javascript':64 'librari':6,17 'lightweight':4 'low':61 'maintain':34 'manual':40 'messag':59 'nativ':51 'ping':53 'ping/pong':41 'provid':25 'requir':55 'server':14 'server-sid':13 'session':37 'side':15,21 'simpl':27 'timeout':46 'version':23 'websocket':8,22,36,52 'work':56 'ws':2,16 'ws-heartbeat':1","created_at":"2026-06-07T17:03:30.092697+00:00","updated_at":"2026-06-07T17:03:30.092697+00:00","problems":[{"fix":"Import from 'ws-heartbeat/client' (browser) or 'ws-heartbeat/server' (Node).","cause":"Importing from root instead of subpath (client/server).","error":"Cannot find module 'ws-heartbeat' or its corresponding type declarations."},{"fix":"Ensure client uses browser WebSocket (or wrappers) and server uses ws.WebSocket from 'ws' package.","cause":"Passing a raw WebSocket instance instead of a ws.WebSocket on server side, or vice versa on client.","error":"TypeError: ws.send is not a function"},{"fix":"Use correct import: import { setWsHeartbeat } from 'ws-heartbeat/client' (client) or 'ws-heartbeat/server' (server).","cause":"Importing the wrong export or using require without proper subpath.","error":"setWsHeartbeat is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/plantain-00/ws-heartbeat#readme","github":"https://github.com/plantain-00/ws-heartbeat","docs":null,"changelog":null,"pypi":null,"npm":"ws-heartbeat","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}