{"id":48198,"library":"iso-websocket","title":"iso-websocket","description":"Isomorphic WebSocket client with auto-reconnect, connection timeout, message queuing, and extensible retry strategy. Works in browser and Node.js. Current stable version is 0.5.0. Supports standard WebSocket API, typed events, and custom reconnection URLs. Differentiates from alternatives like ws or reconnecting-websocket by being isomorphic and providing built-in retry and queue.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/hugomrdias/iso-repo","tags":["javascript","websocket","reconnect","retry","websocket-client","typescript"],"install":[{"cmd":"npm install iso-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add iso-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add iso-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for extensible retry strategy (node-retry)","package":"retry","optional":true}],"imports":[{"note":"Named export, not default. Also available as default export? Check docs. ESM only.","wrong":"import WS from 'iso-websocket'","symbol":"WS","correct":"import { WS } from 'iso-websocket'"},{"note":"Not part of iso-websocket. This package exports WS, not WebSocket.","wrong":"import { WS } from 'iso-websocket'","symbol":"isomorphic-ws","correct":"import { WebSocket } from 'ws'"},{"note":"CommonJS require may not work; package is ESM-only.","wrong":"const WebSocket = require('iso-websocket')","symbol":"WebSocket","correct":"import { WS } from 'iso-websocket'"}],"quickstart":{"code":"import { WS } from 'iso-websocket';\n\nconst ws = new WS('ws://localhost:8080', [], {\n  shouldRetry: (err, attempt) => attempt < 3,\n  connectionTimeout: 5000\n});\n\nws.addEventListener('open', () => {\n  console.log('Connected');\n  ws.send('Hello');\n});\n\nws.addEventListener('message', (e) => {\n  console.log('Received:', e.data);\n});\n\nws.addEventListener('close', () => {\n  console.log('Disconnected');\n});","lang":"typescript","description":"Basic usage: create WebSocket connection with retry and connection timeout."},"warnings":[{"fix":"Install ws as a dependency if using Node.js without bundler.","message":"WS constructor is required. On Node.js, it wraps ws.WebSocket; make sure ws package is installed if not using bundler.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use package.json resolutions or lockfile.","message":"Version 0.x may have breaking changes between minor versions. Pin to exact version.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Set options.queueMessages: false to disable.","message":"Message queuing is enabled by default. If not connected, messages are queued and sent on reconnect.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure you pass url first, then protocols array, then options object.","message":"Some options like 'url' may change. Use constructor signature: new WS(url, protocols?, options?).","severity":"deprecated","affected_versions":">=0.5.0"}],"env_vars":null,"search_vec":"'0.5.0':28 'altern':41 'api':32 'auto':9 'auto-reconnect':8 'browser':21 'built':54 'built-in':53 'client':6,65 'connect':11 'current':24 'custom':36 'differenti':39 'event':34 'extens':16 'iso':2 'iso-websocket':1 'isomorph':4,50 'javascript':59 'like':42 'messag':13 'node.js':23 'provid':52 'queu':14 'queue':58 'reconnect':10,37,46,61 'reconnecting-websocket':45 'retri':17,56,62 'stabl':25 'standard':30 'strategi':18 'support':29 'timeout':12 'type':33 'typescript':66 'url':38 'version':26 'websocket':3,5,31,47,60,64 'websocket-cli':63 'work':19 'ws':43","created_at":"2026-06-07T16:55:24.416467+00:00","updated_at":"2026-06-07T16:55:24.416467+00:00","problems":[{"fix":"npm install ws","cause":"Missing ws dependency on Node.js","error":"Error: Cannot find module 'ws'"},{"fix":"import { WS } from 'iso-websocket'","cause":"Incorrect import; using default import instead of named import","error":"TypeError: WS is not a constructor"},{"fix":"Call ws.send only after 'open' event is fired","cause":"WS instance not ready; waiting for 'open' event needed","error":"TypeError: ws.send 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/hugomrdias/iso-repo/tree/master/packages/iso-websocket","github":"https://github.com/hugomrdias/iso-repo","docs":null,"changelog":null,"pypi":null,"npm":"iso-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}}