{"id":48389,"library":"light-websocket-client","title":"Light Websocket Client","description":"A lightweight TypeScript Websocket client with built-in keep-alive, auto-reconnect with exponential backoff, and application-level authentication. Designed to work with the `light-websocket-server`. Provides a custom protocol header for ping/pong keep-alive since browser WebSocket API cannot send raw ping frames. Suitable for both browser and Node.js environments when paired with the `ws` package on Node. Version 0.0.45, actively maintained.","status":"active","version":"0.0.45","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","websocket","async","typescript"],"install":[{"cmd":"npm install light-websocket-client","lang":"bash","label":"npm"},{"cmd":"yarn add light-websocket-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add light-websocket-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Node.js environment to create WebSocket connections.","package":"ws","optional":true}],"imports":[{"note":"Package exports ESM modules and TypeScript type definitions.","wrong":"const LightWebsocketClientImpl = require('light-websocket-client')","symbol":"LightWebsocketClientImpl","correct":"import { LightWebsocketClientImpl } from 'light-websocket-client'"},{"note":"Options is a named export, not default.","wrong":"const Options = require('light-websocket-client').Options","symbol":"Options","correct":"import { Options } from 'light-websocket-client'"},{"note":"Node-specific client class ready to use with the ws library.","wrong":"","symbol":"LightWebsocketNodeClient","correct":"import { LightWebsocketNodeClient } from 'light-websocket-client'"}],"quickstart":{"code":"import { LightWebsocketNodeClient, Options } from 'light-websocket-client';\n\nconst options = new Options();\noptions.idleTimeout = 50000;\noptions.log = (message, param) => {\n  console.log(message, param);\n};\n\nconst client = new LightWebsocketNodeClient(\n  process.env.WS_URL ?? 'ws://localhost:8888/endpoint',\n  process.env.APP_KEY ?? 'a3a45sfbc7e',\n  process.env.TICKET ?? 'xxx',\n  options\n);\n\nclient.onActive(() => {\n  client.subscribe(['/topic/a']).then(() => {\n    console.log('subscribe succeed');\n  }).catch(e => {\n    console.error('subscribe error', e);\n    client.disconnect();\n  });\n});\n\nclient.onInactive(() => {\n  console.log('onInactive');\n});\n\nclient.onMessage((message) => {\n  console.log('onMessage: ', message);\n});\n\nclient.connect();","lang":"typescript","description":"Shows how to create a WebSocket client with custom options, handle active/inactive events, subscribe to a topic, and connect."},"warnings":[{"fix":"Install 'ws' and either use LightWebsocketNodeClient or subclass LightWebsocketClientImpl with the ws module.","message":"When using in Node.js, you must install the 'ws' package separately and provide a custom implementation extending LightWebsocketClientImpl if not using LightWebsocketNodeClient.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Ensure topics start with '/' and are recognized by the server.","message":"The subscription method requires the server to support the topic pattern. Subscription may fail if topics are not properly formatted.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use client.disconnect() carefully; if you want to temporarily disconnect and reconnect, consider using a flag to manage state.","message":"Auto-reconnect is disabled when calling disconnect() explicitly. It will only re-enable on next connect() call.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Pin to a specific version and test upgrades.","message":"The package version 0.0.45 is below 1.0.0; APIs may change without major version bump.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'0.0.45':71 'activ':72 'aliv':15,45 'api':49 'applic':24 'application-level':23 'async':76 'authent':26 'auto':17 'auto-reconnect':16 'backoff':21 'browser':47,58 'built':11 'built-in':10 'cannot':50 'client':3,8 'custom':38 'design':27 'environ':61 'exponenti':20 'frame':54 'header':40 'javascript':74 'keep':14,44 'keep-al':13,43 'level':25 'light':1,33 'light-websocket-serv':32 'lightweight':5 'maintain':73 'node':69 'node.js':60 'packag':67 'pair':63 'ping':53 'ping/pong':42 'protocol':39 'provid':36 'raw':52 'reconnect':18 'send':51 'server':35 'sinc':46 'suitabl':55 'typescript':6,77 'version':70 'websocket':2,7,34,48,75 'work':29 'ws':66","created_at":"2026-06-07T16:56:24.329953+00:00","updated_at":"2026-06-07T16:56:24.329953+00:00","problems":[{"fix":"Run 'npm install ws' or 'yarn add ws'.","cause":"The 'ws' package is not installed in the Node.js environment.","error":"Cannot find module 'ws'"},{"fix":"Use import { LightWebsocketNodeClient } from 'light-websocket-client' (curly braces).","cause":"Incorrect import: default import used instead of named import.","error":"TypeError: LightWebsocketNodeClient is not a constructor"},{"fix":"Verify the server URL and ensure the server is running.","cause":"The WebSocket server is not running or the URL is incorrect.","error":"Error: connect ECONNREFUSED"}],"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":"light-websocket-client","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}}