Registry / messaging / reconnecting-websocket

reconnecting-websocket

library4.4.0jsnpmunverified

A minimal, dependency-free WebSocket wrapper that automatically reconnects when the connection is closed. Current stable version is 4.4.0, with frequent releases. It implements the standard WebSocket API (both Level0 and Level2 event models), supports custom WebSocket constructors (e.g., the 'ws' library in Node.js), URL providers (sync or async) for dynamic endpoints, connection timeout, exponential backoff with jitter, and message buffering until reconnection. It is designed for multi-platform use (browser, Service Workers, Node.js, React Native) and ships with TypeScript definitions. Unlike alternatives, it has zero dependencies and does not rely on any DOM or EventEmitter libraries.

messaging

npm install reconnecting-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RECONNECTING-WEBSO

reconnecting-websocket

messagingjavascriptv4.4.0

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.

default

✓ import ReconnectingWebSocket from 'reconnecting-websocket'

✗ const ReconnectingWebSocket = require('reconnecting-websocket')

ESM-only from v4. For CommonJS, use the dynamic import: const { default: ReconnectingWebSocket } = await import('reconnecting-websocket')

ReconnectingWebSocket

✓ import ReconnectingWebSocket from 'reconnecting-websocket'

✗ import { ReconnectingWebSocket } from 'reconnecting-websocket'

The package exports a single default export; named import will result in undefined.

Options

✓ import type { Options } from 'reconnecting-websocket'

✗ import { Options } from 'reconnecting-websocket'

Options type is exported as a named type for TypeScript users. Use 'import type' to avoid bundling runtime code.

Shows basic usage: create a ReconnectingWebSocket, listen for open/message/close events, send a message, and close the connection.

import ReconnectingWebSocket from 'reconnecting-websocket'; const url = process.env.WS_URL ?? 'ws://echo.websocket.org'; const rws = new ReconnectingWebSocket(url); rws.addEventListener('open', () => { console.log('connected'); rws.send('Hello, world!'); }); rws.addEventListener('message', (event) => { console.log('Received:', event.data); rws.close(); }); rws.addEventListener('close', () => { console.log('disconnected'); });

Debug

Known issues

breakingThe package is ESM-only from version 4.x. CommonJS require() will break unless using dynamic import.

fix

Use import or dynamic import: const { default: RWS } = await import('reconnecting-websocket')

affects: >=4.0.0

breakingDefault export changed from a named export to a single default export in v4. Importing { ReconnectingWebSocket } gives undefined.

fix

Use default import: import ReconnectingWebSocket from 'reconnecting-websocket'

affects: >=4.0.0

gotchaReconnectingWebSocket does not automatically reconnect if the initial connection fails (e.g., wrong URL). It only reconnects after a successful open and subsequent close.

fix

Set 'startClosed: true' and call .reconnect() manually, or handle initial connection errors via 'error' event.

affects: >=4.0.0

gotchaBuffered messages may exceed the 'maxEnqueuedMessages' limit silently. Messages beyond the limit are dropped.

fix

Monitor the buffer or set maxEnqueuedMessages to a safe value; implement your own backpressure if needed.

affects: >=4.0.0

Errors

Common errors & fixes

Cannot find module 'reconnecting-websocket'

Package not installed in node_modules.

fix

Run: npm install reconnecting-websocket

export 'default' (imported as 'ReconnectingWebSocket') was not found in 'reconnecting-websocket'

Using TypeScript with CommonJS module resolution and importing the default incorrectly.

fix

Add 'esModuleInterop': true in tsconfig.json or use import ReconnectingWebSocket = require('reconnecting-websocket')

ReconnectingWebSocket is not a constructor

Trying to use require('reconnecting-websocket') in ESM-only environment or the import returns an object without default.

fix

Use: import ReconnectingWebSocket from 'reconnecting-websocket' instead of require()

Upgrade

Version history

4.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/pladaria/reconnecting-websocket ↗

packagereconnecting-websocket ↗

homepagehttps://github.com/pladaria/reconnecting-websocket#readme ↗