reconnecting

library4.4.1jsnpmunverified

A WebSocket client that automatically reconnects when the connection is closed. Stable version 4.4.1, actively maintained. Provides a WebSocket API compatible interface with Level0 and Level2 event models. Key differentiators: dependency-free, multi-platform (Web, ServiceWorkers, Node.js, React Native), configurable reconnect behavior, connection timeout handling, buffering of messages during disconnection, and support for dynamic server URLs via string, function, or async function.

messaging

npm install reconnecting

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RECONNECTING

reconnecting

messagingjavascriptv4.4.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.

default

✓ import ReconnectingWebSocket from 'reconnecting-websocket'

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

Since v4, package is ESM-only. Use default import; named import is not supported.

Options

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

✗ import { Options } from 'reconnecting-websocket'

Options is a TypeScript type, not a runtime value. Use type import to avoid runtime errors.

UrlProvider

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

✗ import { UrlProvider } from 'reconnecting-websocket'

UrlProvider is a TypeScript type representing string | (() => string) | (() => Promise<string>). Use type import.

Creates a reconnecting WebSocket, sends a message on open, logs received data, and handles close/error events.

import ReconnectingWebSocket from 'reconnecting-websocket'; const rws = new ReconnectingWebSocket('wss://echo.websocket.org'); rws.addEventListener('open', () => { console.log('Connected'); rws.send('Hello Server!'); }); rws.addEventListener('message', (event: MessageEvent) => { console.log('Received:', event.data); rws.close(); }); rws.addEventListener('close', () => { console.log('Disconnected'); }); rws.addEventListener('error', (event: Event) => { console.error('Error:', event); });

Debug

Known issues

breakingSince v4, package is ESM-only. CommonJS require() will throw.

fix

Use import syntax. If you need CJS, use v3.x or use dynamic import().

affects: >=4.0.0

gotchaThe 'message' event data type varies by environment: in browsers it's 'string | Blob | ArrayBuffer', in Node.js it's 'string | Buffer'.

fix

Check event.data type before processing. On Node.js, use ws package's 'blob' option to normalize.

affects: *

gotchaOption 'startClosed: true' requires calling .reconnect() to connect; otherwise the WebSocket stays closed.

fix

If using startClosed, ensure to call rws.reconnect() when you want to connect.

affects: *

gotchaThe constructor does not throw on invalid URL; errors are emitted on the 'error' event.

fix

Attach an error listener before or immediately after construction.

affects: *

deprecatedOption 'WebSocket' expects a constructor that implements the WebSocket interface. Passing non-standard constructors may cause unexpected behavior.

fix

Ensure the provided WebSocket constructor matches the standard WebSocket API (e.g., the 'ws' package).

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: ReconnectingWebSocket is not a constructor

Using require() in an ESM-only package (v4+).

fix

Change to import ReconnectingWebSocket from 'reconnecting-websocket'

Uncaught (in promise) TypeError: Failed to construct 'WebSocket': The URL '...' is invalid.

The provided URL is invalid (e.g., wrong protocol or malformed).

fix

Ensure the URL starts with 'ws://' or 'wss://' and is correctly formatted.

Upgrade

Version history

4.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

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

packagereconnecting ↗

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