snub-ws

library4.2.1jsnpmunverified

WebSocket server middleware for the snub Redis-based messaging framework, version 4.2.1, distributed as an ESM-only package (CJS still supported via dynamic require). Built on uWebSockets.js, it provides a high-performance WebSocket layer with built-in authentication (function, snub event, or HTTP Basic Auth), rate limiting, idle timeout, origin restrictions, backpressure handling, and message offloading to HTTP for large payloads. Requires both snub and Redis. The client protocol uses JSON arrays for structured messaging with reply IDs.

messaging

npm install snub-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SNUB-WS

snub-ws

messagingjavascriptv4.2.1

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.

SnubWS (default)

✓ import SnubWS from 'snub-ws'

✗ const SnubWS = require('snub-ws').default

Default export for ESM; CJS users can use const SnubWS = require('snub-ws').default

SnubWS (default), CJS

✓ const SnubWS = require('snub-ws')

✗ const { SnubWS } = require('snub-ws')

CommonJS require returns the default export directly; named destructuring fails

SnubWS

✓ import SnubWS from 'snub-ws'

✗ import { SnubWS } from 'snub-ws'

Named import SnubWS does not exist; the package exports only a default function

Sets up a basic WebSocket server on port 8585 with no authentication, and listens for 'ws:hello' events.

import Snub from 'snub'; import SnubWS from 'snub-ws'; const snub = new Snub({ host: 'localhost' }); snub.use(SnubWS({ port: 8585, auth: false })); snub.on('ws:hello', (event, reply) => { console.log('message from', event.from?.username, ':', event.payload); reply('hi back'); });

Debug

Known issues

breakingIn snub-ws v4, the default export is ESM-only; CommonJS require works but may require .default property in some bundlers.

fix

Use import SnubWS from 'snub-ws' or const SnubWS = require('snub-ws').default

affects: >=4.0.0

deprecatedThe `includeRaw` option is deprecated in v4.2.0; use event-level debugging instead.

fix

Remove includeRaw and log manually if needed

affects: >=4.2.0

gotchaIf `auth` is a string (event name), the client must be authenticated via `_auth` message; otherwise the connection is rejected after `authTimeout`.

fix

Ensure client sends `_auth` message promptly or set auth: false for unauthenticated connections.

affects: >=4.0.0

gotchaThe `idleTimeout` default is 960000 ms (16 minutes) but uWebSockets.js limits it to 960 seconds maximum; values above 960000 are silently capped.

fix

Set idleTimeout <= 960000 (or 960 seconds)

affects: >=4.0.0

gotchaRate limiting (`throttle`) applies per connection; if a client opens multiple connections, each is throttled independently.

fix

Consider using 'maxConnections' to limit clients per IP if needed.

affects: >=4.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

snub-ws v4 is ESM-only but required via CJS require()

fix

Use dynamic import: const SnubWS = (await import('snub-ws')).default

TypeError: SnubWS is not a constructor

Importing SnubWS as a named import instead of default

fix

Use import SnubWS from 'snub-ws' (default import)

Cannot find module 'snub'

snub is a peer dependency and not installed

fix

npm install snub

Upgrade

Version history

4.2.1latest on npm

Audit

Dependencies

snubrequiredCore dependency: snub-ws registers as middleware on a Snub instance

uWebSockets.jsrequiredUnderlying WebSocket server implementation

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cokeeffekt/snub-ws ↗

packagesnub-ws ↗

homepagehttps://github.com/cokeeffekt/snub-ws#readme ↗