workersocket

library0.2.3jsnpmunverified

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.

messaging

npm install workersocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORKERSOCKET

workersocket

messagingjavascriptv0.2.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

WorkerSocket

✓ import { WorkerSocket } from 'workersocket'

✗ const WorkerSocket = require('workersocket')

Package is ESM-only. CommonJS require will throw an error.

default

✓ import WorkerSocket from 'workersocket'

✗ import { default as WorkerSocket } from 'workersocket'

No default export. Only named export for WorkerSocket.

WorkerSocket

✓ const { WorkerSocket } = await import('workersocket')

✗ const { WorkerSocket } = require('workersocket')

Dynamic import works in both browser and Node, but require fails.

Shows creating a WorkerSocket, handling open/message/error events, and sending a message.

import { WorkerSocket } from 'workersocket'; const socket = new WorkerSocket('wss://echo.websocket.org'); socket.onopen = () => { console.log('Connected'); socket.send('Hello Worker!'); }; socket.onmessage = (event) => { console.log('Received:', event.data); socket.close(); }; socket.onerror = (error) => { console.error('WebSocket error:', error); };

Debug

Known issues

breakingNo default export — only named export WorkerSocket.

fix

Use `import { WorkerSocket } from 'workersocket'` or `const { WorkerSocket } = await import('workersocket')`.

affects: >=0.1.0

gotchaWorkerSocket 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.

fix

Test your code in both browser and Node environments. The fallback 'ws' object has slightly different API (e.g., no binaryType).

affects: >=0.1.0

gotchaThe 'ws' peer dependency is required in Node.js but unused in browser. If you omit it, the package will fail to start in Node.

fix

Install 'ws' as a dependency: `npm install workersocket ws`.

affects: >=0.1.0

deprecatedConstructor signature: only URL is required; optional second argument for protocols (array of strings) but no support for options object.

fix

No fix needed, but be aware that unlike some WebSocket wrappers, WorkerSocket does not accept an options argument.

affects: >=0.2.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'ws'

The 'ws' peer dependency is missing, which is required in Node.js.

fix

Run `npm install ws` (or add 'ws' to your package.json dependencies).

TypeError: Cannot read properties of undefined (reading 'postMessage')

Attempting to use WorkerSocket in an environment that does not support Web Workers (e.g., older browsers or Node without worker_threads).

fix

Upgrade Node.js version (>=12 for worker_threads) or use a bundler with web worker support if targeting older browsers.

SyntaxError: The requested module 'workersocket' does not provide an export named 'default'

Using a default import when the package only exports a named export.

fix

Change to `import { WorkerSocket } from 'workersocket'`.

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Calling require('workersocket') which is ESM-only.

fix

Use `import` or dynamic `import()` instead of `require()`.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

wsoptionalFallback WebSocket implementation for Node.js where Web Workers are not available

Agent activity

27 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Breq16/workersocket ↗

packageworkersocket ↗

homepagehttps://github.com/Breq16/workersocket#readme ↗