{"id":49390,"library":"sockette-dynamic-url","title":"Sockette","description":"Sockette is a tiny (367 bytes) WebSocket wrapper that automatically reconnects on connection loss. Current stable version is 2.0.7. Released on npm, it provides a minimal API for managing WebSocket connections with configurable timeout and max reconnection attempts. It supports event listeners for open, message, close, reconnect, and maximum attempts reached events. Unlike raw WebSocket, it allows reusing a single instance without redeclaring listeners. It ships TypeScript types and is compatible with both browser and Node.js (with WebSocket polyfill).","status":"active","version":"2.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/sockette","tags":["javascript","socket","reconnect","websocket","typescript"],"install":[{"cmd":"npm install sockette-dynamic-url","lang":"bash","label":"npm"},{"cmd":"yarn add sockette-dynamic-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add sockette-dynamic-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Sockette is a default export. ESM import is recommended but CJS require works.","wrong":"const Sockette = require('sockette')","symbol":"Sockette","correct":"import Sockette from 'sockette'"},{"note":"Named import also works due to named export in package. Both default and named are supported.","wrong":"","symbol":"Sockette","correct":"import { Sockette } from 'sockette'"},{"note":"Redundant but not incorrect. Prefer direct default import.","wrong":"import { default as Sockette } from 'sockette'","symbol":"Sockette","correct":"import Sockette from 'sockette'"}],"quickstart":{"code":"import Sockette from 'sockette';\n\nconst ws = new Sockette('wss://example.com/ws', {\n  timeout: 5000,\n  maxAttempts: 10,\n  onopen: e => console.log('Connected'),\n  onmessage: e => console.log('Received:', e.data),\n  onreconnect: e => console.log('Reconnecting...'),\n  onmaximum: e => console.log('Max attempts reached'),\n  onclose: e => console.log('Closed'),\n  onerror: e => console.log('Error:', e)\n});\n\nws.send('Hello');\nws.json({ type: 'ping' });\nsetTimeout(() => ws.reconnect(), 10000);","lang":"typescript","description":"Shows creating a Sockette instance with all event handlers, sending text and JSON, and manually reconnecting after 10 seconds."},"warnings":[{"fix":"Set `maxAttempts: Infinity` or omit the option.","message":"Passing `maxAttempts: -1` disables reconnection attempts, but this is counterintuitive. Use Infinity or omit to keep default.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure timeout value is in milliseconds (e.g., 5000 for 5 seconds).","message":"The `timeout` option is in milliseconds, not seconds. Common mistake to pass 5 instead of 5000.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use a WebSocket polyfill like `ws` and assign globally: `global.WebSocket = require('ws');`","message":"Sockette does not polyfill WebSocket for Node.js. Must provide a WebSocket implementation (e.g., `ws`) in non-browser environments.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use `event.target` to access the WebSocket instance inside event handlers.","message":"Event listeners passed in options are bound to the Sockette instance, not the WebSocket. Access the underlying WebSocket via `event.target`.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Be aware that the counter resets; plan logic accordingly if you need persistent retry tracking.","message":"Sockette resets its attempt counter after a successful connection, so reconnection behavior may not be as expected after a full reconnect cycle.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'2.0.7':20 '367':6 'allow':58 'api':28 'attempt':39,51 'automat':11 'browser':75 'byte':7 'close':47 'compat':72 'configur':34 'connect':14,32 'current':16 'event':42,53 'instanc':62 'javascript':81 'listen':43,65 'loss':15 'manag':30 'max':37 'maximum':50 'messag':46 'minim':27 'node.js':77 'npm':23 'open':45 'polyfil':80 'provid':25 'raw':55 'reach':52 'reconnect':12,38,48,83 'redeclar':64 'releas':21 'reus':59 'ship':67 'singl':61 'socket':82 'sockett':1,2 'stabl':17 'support':41 'timeout':35 'tini':5 'type':69 'typescript':68,85 'unlik':54 'version':18 'websocket':8,31,56,79,84 'without':63 'wrapper':9","created_at":"2026-06-07T17:01:32.364152+00:00","updated_at":"2026-06-07T17:01:32.364152+00:00","problems":[{"fix":"Install `ws` and assign `global.WebSocket = require('ws');` before using Sockette.","cause":"Using Sockette in Node.js without a WebSocket polyfill.","error":"Error: WebSocket is not defined"},{"fix":"Ensure send is called after the `onopen` event has fired, or inside a callback.","cause":"Calling send on the Sockette instance but the connection is not yet open.","error":"TypeError: ws.send is not a function"},{"fix":"Use a valid WebSocket URL with proper scheme, e.g., 'wss://example.com/ws'.","cause":"URL string missing protocol (ws:// or wss://) or malformed.","error":"Uncaught DOMException: Failed to construct 'WebSocket': The URL 'ws://example.com' is invalid."},{"fix":"Use `import Sockette from 'sockette'` (default import) or `const Sockette = require('sockette')`.","cause":"Using named import `{ Sockette }` when only default export exists (or vice versa).","error":"TypeError: sockette_1.default is not a constructor"}],"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/lukeed/sockette","github":"https://github.com/lukeed/sockette","docs":null,"changelog":null,"pypi":null,"npm":"sockette-dynamic-url","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}}