wwws

library1.3.3jsnpmunverified

A cross-runtime WebSocket implementation (Node, Bun, Deno) with built-in SOCKS5/SOCKS5h proxy support. Version 1.3.3 is the latest stable release, published in 2023. It provides a drop-in replacement for the 'ws' library, adding a 'proxy' constructor parameter. Unlike similar proxy-focused WebSocket packages, wwws works natively across all three major JavaScript runtimes without platform-specific polyfills. It supports both ESM and CommonJS module formats and ships TypeScript type definitions. The library reimplements the full WebSocket class with event handling, message sending, and connection management, though it is not fully spec-compliant (e.g., missing some standard properties on event objects).

networking

npm install wwws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WWWS

wwws

networkingjavascriptv1.3.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.

WWWebSocket

✓ import { WWWebSocket } from 'wwws'

✗ import WWWebSocket from 'wwws'

WWWebSocket is both a named export and the default export, so both patterns work. Using named import is recommended for clarity.

default import

✓ import WWWebSocket from 'wwws'

✗ const { default: WWWebSocket } = require('wwws')

CommonJS require also works: const { WWWebSocket } = require('wwws'). Default export is available as module.exports.

CommonJS require

✓ const { WWWebSocket } = require('wwws')

✗ const WWWebSocket = require('wwws')

The default export is an object containing WWWebSocket. Direct require returns the module object, not the constructor directly.

Creates a WebSocket connection through a SOCKS5 proxy and handles basic events.

import { WWWebSocket } from 'wwws'; const ws = new WWWebSocket('wss://echo.websocket.org', { proxy: process.env.PROXY_URL ?? 'socks5://user:pass@127.0.0.1:1080' }); ws.onopen = () => { console.log('Connected!'); ws.send('Hello wwws!'); }; ws.onmessage = (event) => { console.log('Received:', event.data); ws.close(); }; ws.onerror = (error) => { console.error('WebSocket error:', error.message); }; ws.onclose = (event) => { console.log('Disconnected, code:', event.code); };

Debug

Known issues

gotchawwws is NOT spec-compliant. Event objects may lack required properties (e.g., onmessage event may not have origin, lastEventId, etc.).

fix

If you need full spec compliance, consider using standard WebSocket API or 'ws' library for browser/Node respectively.

affects: *

gotchawwws does NOT support Cloudflare Workers or other 'fake Node' platforms that rewrite Node internals, because it relies on native Node modules (crypto, dns, net, tls, zlib) that are stubbed or missing in such environments.

fix

Run wwws only on Node.js, Deno, or Bun. For Cloudflare Workers, use a different WebSocket library that supports their runtime.

affects: *

gotchaThe 'agent' parameter is supported only to the extent that a proxy URL is extracted from it. Using 'agent' directly is not recommended.

fix

Use the 'proxy' parameter directly instead of 'agent' for reliable proxy configuration.

affects: *

gotchaSOCKS5 proxy requires the 'node:dns' module (dns.lookup) for hostname resolution; SOCKS5h bypasses DNS and uses the proxy's DNS. If your runtime lacks dns.lookup, use socks5h:// schemes.

fix

Use socks5h:// proxy URL to avoid dependency on node:dns.

affects: *

gotchapermessage-deflate compression requires node:zlib (deflateRaw/inflateRaw). If those modules are unavailable, compression will silently not work.

fix

Ensure node:zlib is available in your runtime, or avoid using permessage-deflate.

affects: *

Errors

Common errors & fixes

Error: Cannot find module 'wwws'

The package is not installed.

fix

Run `npm install wwws` or `bun add wwws` or `pnpm add wwws`.

TypeError: WWWebSocket is not a constructor

Using CommonJS require incorrectly: require('wwws') returns the module object, not the constructor directly.

fix

Use `const { WWWebSocket } = require('wwws');`

TypeError: dns.lookup is not a function

Using a SOCKS5 proxy (not socks5h) in an environment where node:dns is not available or stubbed (e.g., bun sometimes, or custom runtimes).

fix

Switch to a socks5h:// proxy URL, or ensure node:dns is properly polyfilled.

Error: The 'proxy' parameter must be a string or an object with 'toProxyURL' method

Passing an invalid proxy argument to the constructor.

fix

Ensure the proxy parameter is a string like 'socks5://host:port' or an object with a toProxyURL() method.

Upgrade

Version history

1.3.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

37 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/VillainsRule/wwws ↗

packagewwws ↗

homepagehttps://github.com/VillainsRule/wwws ↗