{"id":49753,"library":"workersocket","title":"WorkerSocket","description":"An API-compatible WebSocket implementation that runs inside a Web Worker, offloading network I/O from the main thread. Current version 0.2.3, released as an ES module only. The library mirrors the standard WebSocket interface (onmessage, onopen, send, close) but executes in a worker context. Key differentiators: zero dependency on the main thread, fallback to Node's 'ws' package when Web Workers are unsupported (e.g., Node.js), and no bundle size increase for browser users. Ideal for libraries or applications that need to maintain a WebSocket connection without blocking the UI.","status":"active","version":"0.2.3","language":"javascript","source_language":"en","source_url":"https://github.com/Breq16/workersocket","tags":["javascript","websocket","worker"],"install":[{"cmd":"npm install workersocket","lang":"bash","label":"npm"},{"cmd":"yarn add workersocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add workersocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Fallback WebSocket implementation for Node.js where Web Workers are not available","package":"ws","optional":true}],"imports":[{"note":"Package is ESM-only. CommonJS require will throw an error.","wrong":"const WorkerSocket = require('workersocket')","symbol":"WorkerSocket","correct":"import { WorkerSocket } from 'workersocket'"},{"note":"No default export. Only named export for WorkerSocket.","wrong":"import { default as WorkerSocket } from 'workersocket'","symbol":"default","correct":"import WorkerSocket from 'workersocket'"},{"note":"Dynamic import works in both browser and Node, but require fails.","wrong":"const { WorkerSocket } = require('workersocket')","symbol":"WorkerSocket","correct":"const { WorkerSocket } = await import('workersocket')"}],"quickstart":{"code":"import { WorkerSocket } from 'workersocket';\n\nconst socket = new WorkerSocket('wss://echo.websocket.org');\n\nsocket.onopen = () => {\n  console.log('Connected');\n  socket.send('Hello Worker!');\n};\n\nsocket.onmessage = (event) => {\n  console.log('Received:', event.data);\n  socket.close();\n};\n\nsocket.onerror = (error) => {\n  console.error('WebSocket error:', error);\n};","lang":"javascript","description":"Shows creating a WorkerSocket, handling open/message/error events, and sending a message."},"warnings":[{"fix":"Use `import { WorkerSocket } from 'workersocket'` or `const { WorkerSocket } = await import('workersocket')`.","message":"No default export — only named export WorkerSocket.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Test your code in both browser and Node environments. The fallback 'ws' object has slightly different API (e.g., no binaryType).","message":"WorkerSocket uses Web Workers internally; in Node.js it falls back to native 'ws' module, but Web Workers are not available, which may cause unexpected behavior if migrating from browser-only code.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install 'ws' as a dependency: `npm install workersocket ws`.","message":"The 'ws' peer dependency is required in Node.js but unused in browser. If you omit it, the package will fail to start in Node.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"No fix needed, but be aware that unlike some WebSocket wrappers, WorkerSocket does not accept an options argument.","message":"Constructor signature: only URL is required; optional second argument for protocols (array of strings) but no support for options object.","severity":"deprecated","affected_versions":">=0.2.0"}],"env_vars":null,"search_vec":"'0.2.3':23 'api':4 'api-compat':3 'applic':80 'block':89 'browser':74 'bundl':70 'close':40 'compat':5 'connect':87 'context':46 'current':21 'depend':50 'differenti':48 'e.g':66 'es':27 'execut':42 'fallback':55 'i/o':16 'ideal':76 'implement':7 'increas':72 'insid':10 'interfac':36 'javascript':92 'key':47 'librari':31,78 'main':19,53 'maintain':84 'mirror':32 'modul':28 'need':82 'network':15 'node':57 'node.js':67 'offload':14 'onmessag':37 'onopen':38 'packag':60 'releas':24 'run':9 'send':39 'size':71 'standard':34 'thread':20,54 'ui':91 'unsupport':65 'user':75 'version':22 'web':12,62 'websocket':6,35,86,93 'without':88 'worker':13,45,63,94 'workersocket':1 'ws':59 'zero':49","created_at":"2026-06-07T17:03:26.283359+00:00","updated_at":"2026-06-07T17:03:26.283359+00:00","problems":[{"fix":"Run `npm install ws` (or add 'ws' to your package.json dependencies).","cause":"The 'ws' peer dependency is missing, which is required in Node.js.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'ws'"},{"fix":"Upgrade Node.js version (>=12 for worker_threads) or use a bundler with web worker support if targeting older browsers.","cause":"Attempting to use WorkerSocket in an environment that does not support Web Workers (e.g., older browsers or Node without worker_threads).","error":"TypeError: Cannot read properties of undefined (reading 'postMessage')"},{"fix":"Change to `import { WorkerSocket } from 'workersocket'`.","cause":"Using a default import when the package only exports a named export.","error":"SyntaxError: The requested module 'workersocket' does not provide an export named 'default'"},{"fix":"Use `import` or dynamic `import()` instead of `require()`.","cause":"Calling require('workersocket') which is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"}],"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/Breq16/workersocket#readme","github":"https://github.com/Breq16/workersocket","docs":null,"changelog":null,"pypi":null,"npm":"workersocket","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}}