{"id":49830,"library":"zerva-websocket","title":"Zerva WebSocket","description":"Zerva WebSocket is a lightweight, resilient WebSocket module for the Zerva event-driven server framework. Version 0.3.5 provides plain WebSocket connections with automatic reconnection, heartbeat (ping/pong), and supports three communication patterns: raw binary channels (via Zeed Channel), typed message interfaces (via Zeed Message), and PubSub. It is designed for Node.js (>=14.13.1) with full TypeScript support. Key differentiators include transparent reconnection that preserves the same channel object, binary-first encoding with pluggable codecs, and tight integration with Zeed's messaging primitives. Ideal for applications needing simple, reliable WebSocket communication without the overhead of Socket.IO.","status":"active","version":"0.3.5","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","server","typescript","event","websocket","socket","zerva","zeed"],"install":[{"cmd":"npm install zerva-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add zerva-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add zerva-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides Channel, Message, and PubSub primitives used by zerva-websocket","package":"zeed","optional":false},{"reason":"Core framework for event handling and HTTP integration","package":"zerva","optional":false},{"reason":"HTTP module required to upgrade server to WebSocket (useHttp is a prerequisite)","package":"zerva-http","optional":false}],"imports":[{"note":"ESM only; CommonJS require is not supported.","wrong":"const { useWebSocket } = require('zerva-websocket')","symbol":"useWebSocket","correct":"import { useWebSocket } from 'zerva-websocket'"},{"note":"The `on` function is exported by the `zerva` core package, not by `zerva-websocket`.","wrong":"import { on } from 'zerva-websocket'","symbol":"on","correct":"import { on } from 'zerva'"},{"note":"WebSocketConnection is a class for client-side use, exported from zerva-websocket.","wrong":"import { WebSocketConnection } from 'zerva'","symbol":"WebSocketConnection","correct":"import { WebSocketConnection } from 'zerva-websocket'"},{"note":"useMessageHub is from the zeed package, not from zerva-websocket.","wrong":"import { useMessageHub } from 'zerva-websocket'","symbol":"useMessageHub","correct":"import { useMessageHub } from 'zeed'"}],"quickstart":{"code":"import { useWebSocket, WebSocketConnection } from 'zerva-websocket'\nimport { useHttp } from 'zerva-http'\nimport { on } from 'zerva'\nimport { useMessageHub } from 'zeed'\n\n// Server\nuseHttp({ port: 8080 })\nuseWebSocket()\n\non('webSocketConnect', ({ channel }) => {\n  const hub = useMessageHub({ channel })\n  hub.listen({\n    echo(msg) { return msg }\n  })\n})\n\n// Client\nconst channel = new WebSocketConnection('ws://localhost:8080')\nconst send = useMessageHub({ channel }).send()\nconst response = await send.echo('Hello')\nconsole.log(response) // 'Hello'","lang":"typescript","description":"Sets up a WebSocket server using Zerva, listens for connections, echoes messages via MessageHub, and connects from client side."},"warnings":[{"fix":"Always pass a full URL to the WebSocketConnection constructor when running in Node.js, e.g., new WebSocketConnection('ws://localhost:8080').","message":"WebSocketConnection requires the WebSocket protocol URL (ws:// or wss://) for client connections; otherwise it defaults to window.location but may fail in Node.js.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure useHttp() is called before useWebSocket().","message":"useWebSocket() must be called after useHttp() to attach to the HTTP server; otherwise it will throw or not work.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"import { on } from 'zerva'","message":"The `on` function for events like 'webSocketConnect' must be imported from 'zerva', not 'zerva-websocket'.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Set 'moduleResolution' to 'node' (or 'nodenext') in tsconfig.json.","message":"TypeScript types are shipped but may require tsconfig to have 'moduleResolution' set to 'node' or 'nodenext' to resolve correctly.","severity":"gotcha","affected_versions":">=0.3.0"}],"env_vars":null,"search_vec":"'0.3.5':20 '14.13.1':54 'applic':87 'automat':26 'binari':36,71 'binary-first':70 'channel':37,40,68 'codec':76 'communic':33,92 'connect':24 'design':51 'differenti':60 'driven':16 'encod':73 'event':15,101 'event-driven':14 'first':72 'framework':18 'full':56 'heartbeat':28 'ideal':85 'includ':61 'integr':79 'interfac':43 'javascript':98 'key':59 'lightweight':7 'messag':42,46,83 'modul':10 'need':88 'node.js':53 'object':69 'overhead':95 'pattern':34 'ping/pong':29 'plain':22 'pluggabl':75 'preserv':65 'primit':84 'provid':21 'pubsub':48 'raw':35 'reconnect':27,63 'reliabl':90 'resili':8 'server':17,99 'simpl':89 'socket':103 'socket.io':97 'support':31,58 'three':32 'tight':78 'transpar':62 'type':41 'typescript':57,100 'version':19 'via':38,44 'websocket':2,4,9,23,91,102 'without':93 'zeed':39,45,81,105 'zerva':1,3,13,104","created_at":"2026-06-07T17:03:48.848844+00:00","updated_at":"2026-06-07T17:03:48.848844+00:00","problems":[{"fix":"npm install zerva-websocket","cause":"Missing installation of zerva-websocket package","error":"Error: Cannot find module 'zerva-websocket'"},{"fix":"import { on } from 'zerva'","cause":"`on` imported from zerva-websocket instead of zerva","error":"TypeError: on is not a function"},{"fix":"Call useHttp() before useWebSocket()","cause":"useWebSocket() invoked before HTTP server is created","error":"Error: useWebSocket must be called after useHttp"}],"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":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"zerva-websocket","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}}