websocket-front

library1.1.4jsnpmunverified

A lightweight TypeScript wrapper around the native browser WebSocket API, providing automatic reconnection and heartbeat detection out of the box. Version 1.1.4 is the latest stable release. It distinguishes itself by requiring zero configuration for basic usage — both reconnect and heartbeat are enabled by default — while still offering customizable options for timeouts, retry limits, and callbacks. Pure client-side library with no server-side dependencies. Ships TypeScript type definitions. Released at a moderate cadence (last update April 2024).

messaging

npm install websocket-front

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEBSOCKET-FRONT

websocket-front

messagingjavascriptv1.1.4

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.

Socket

✓ import Socket from 'websocket-front'

✗ import { Socket } from 'websocket-front'

Default export only; named import will result in undefined.

Socket

✓ import Socket from 'websocket-front'

✗ const Socket = require('websocket-front')

Package is ESM-only; CommonJS require is not supported.

SocketOptions / Options interface

✓ import type { SocketOptions } from 'websocket-front'

TypeScript users can import the options interface as a type for the second constructor argument.

SocketEvents

✓ import type { SocketEvents } from 'websocket-front'

Optional type import for event callback signatures.

Shows default connection with automatic reconnect and heartbeat, event handling, send, and close.

import Socket from 'websocket-front'; const socket = new Socket('wss://echo.websocket.org'); socket.on('open', () => { console.log('Connected'); socket.send('Hello server!'); }); socket.on('message', (event: MessageEvent) => { console.log('Received:', event.data); }); socket.on('error', (error: Event) => { console.error('WebSocket error:', error); }); socket.on('close', (event: CloseEvent) => { console.log('Disconnected'); }); // After 5 seconds close the connection setTimeout(() => { socket.close(); }, 5000);

Debug

Known issues

gotchaThe 'pingMsg' option defaults to 'ping' but for production you should use a JSON string like JSON.stringify({type:'ping'}) to match your server protocol.

fix

Set pingMsg: JSON.stringify({ messageType: '0', content: 'ping' }) or as per your backend.

affects: >=1.0.0

gotchaEvent callbacks onOpen, onMessage, onError, onClose are passed in the second argument constructor object, but you can also use the .on() method after instantiation.

fix

Either pass callbacks in options or use socket.on('event', handler) – not both for same event, as both will fire.

affects: >=1.0.0

gotchaThe 'reconnectTimeout' is in milliseconds, but the default is 300 ms. This is very aggressive; consider increasing it to 1000-3000 ms to avoid overwhelming server.

fix

Set reconnectTimeout: 3000 (3 seconds) in options.

affects: >=1.0.0

gotchaWhen 'isReconnect' is true (default), calling socket.close() will trigger reconnect. To permanently close, either set isReconnect: false or call socket.close() and then manually clean up references.

fix

Set isReconnect: false before closing, or call socket.close() and set socket = null.

affects: >=1.0.0

gotchaThe 'pingTimeout' and 'pongTimeout' defaults (300ms each) are extremely low. Typical heartbeat intervals are 30-60 seconds. This may cause unnecessary reconnects.

fix

Set pingTimeout: 30000 (30s) and pongTimeout: 5000 (5s).

affects: >=1.0.0

Errors

Common errors & fixes

Uncaught TypeError: Cannot read properties of undefined (reading 'send')

Attempting to call socket.send() before WebSocket connection is established.

fix

Call send() only inside an 'open' event handler or after checking socket.readyState === WebSocket.OPEN.

Error: WebSocket is closed before the connection is established.

Calling socket.close() immediately after construction, before the connection has time to open.

fix

Ensure close() is called after the connection is open (e.g., inside a setTimeout or after user action).

Uncaught (in promise) DOMException: Failed to construct 'WebSocket': The URL 'ws://example.com' is invalid.

Passed an invalid URL (e.g., missing protocol or malformed).

fix

Use valid WebSocket URLs: ws:// or wss:// followed by host:port/path.

Upgrade

Version history

1.1.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/yquanmei/websocket-front ↗

packagewebsocket-front ↗

homepagehttps://github.com/yquanmei/websocket-front#readme ↗