sturdy-websocket

library0.2.1jsnpmunverified

Tiny (<4kb gzipped) WebSocket wrapper that automatically reconnects and buffers messages sent while disconnected. Version 0.2.1 is the latest stable release (no update cadence documented). Fully implements the standard WebSocket API (including readyState, EventTarget, and bufferedAmount) so it can be a drop-in replacement. The last release was in 2019 and the package appears to be in maintenance mode. Differentiates from alternatives like reconnecting-websocket by providing a complete WebSocket-compatible interface with configurable reconnection strategies (backoff, timeouts, max attempts).

messaging

npm install sturdy-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STURDY-WEBSOCKET

sturdy-websocket

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

SturdyWebSocket

✓ import SturdyWebSocket from 'sturdy-websocket'

✗ import { SturdyWebSocket } from 'sturdy-websocket'

Default export only; named import will fail.

SturdyWebSocket

✓ const SturdyWebSocket = require('sturdy-websocket').default

✗ const SturdyWebSocket = require('sturdy-websocket')

In CommonJS, require returns the module object, so you must use .default.

SturdyWebSocket

✓ import type SturdyWebSocket from 'sturdy-websocket'

TypeScript type import works as expected since the package ships types.

Creates a sturdy WebSocket with exponential backoff reconnection and event handlers for open, message, down, and reopen.

import SturdyWebSocket from 'sturdy-websocket' const ws = new SturdyWebSocket('wss://echo.websocket.org', { minReconnectDelay: 1000, maxReconnectDelay: 30000, reconnectBackoffFactor: 1.5, maxReconnectAttempts: 10, debug: true }) ws.onopen = () => ws.send('Hello, world!') ws.onmessage = (event) => console.log('Received:', event.data) ws.ondown = (closeEvent) => console.log('Connection lost:', closeEvent.reason) ws.onreopen = () => console.log('Reconnected!') // Simulate close after 5 seconds ts.setTimeout(() => ws.close(), 5000)

Debug

Known issues

gotchaonclose is only called when the connection is permanently closed, not on temporary disconnects.

fix

Use 'down' and 'reopen' events for temporary disconnection notifications.

affects: >=0.1.0

gotchaThe ws library must be manually installed for Node.js environments; it is a peer dependency.

fix

Run 'npm install ws' alongside sturdy-websocket.

affects: >=0.2.0

gotchaSilent connection loss (e.g., server power outage) cannot be detected automatically; implement application-level ping/pong.

fix

Send periodic messages and await responses to detect dead connections.

affects: >=0.1.0

deprecatedThe 'options' parameter order changed between versions; old code passing options as second argument may break.

fix

Ensure options are passed as the third argument (after url and protocol) or as the second if no protocol.

affects: <0.2.0

gotchaCalling send() before the connection opens buffers messages indefinitely if the connection never opens.

fix

Check readyState === OPEN before sending, or use maxReconnectAttempts to limit retries.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'ws'

Missing peer dependency 'ws' in Node.js environment.

fix

npm install ws

TypeError: SturdyWebSocket is not a constructor

Using named import instead of default import.

fix

Change to 'import SturdyWebSocket from 'sturdy-websocket'' (no curly braces).

SturdyWebSocket is not defined

Using require() without .default in CommonJS.

fix

Use 'const SturdyWebSocket = require('sturdy-websocket').default'.

Uncaught DOMException: Failed to construct 'WebSocket': The URL 'undefined' is invalid.

No URL provided or URL is undefined.

fix

Always pass a valid WebSocket URL as the first argument.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

wsoptionalUsed as the WebSocket implementation in Node.js environments

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubgit://github.com/dphilipson/sturdy-websocket ↗

packagesturdy-websocket ↗

homepagehttps://github.com/dphilipson/sturdy-websocket ↗