maxsocket

library1.0.2jsnpmunverified

maxsocket is a lightweight (~0.9 kB min+gzip) WebSocket client library offering built-in auto-reconnect, offline message queuing, JSON handling, and event routing. Current stable version is 1.0.2. It provides a functional API with explicit lifecycle handlers (onConnect, onMessage, onClose) instead of generic event listeners, and includes an event routing system for structured server messages. Unlike alternatives like reconnecting-websocket (2.6 kB) and simple-websocket (13.8 kB), maxsocket focuses on small bundle size, simplicity for modern frontends (React, Vue, Svelte, vanilla JS), and built-in features that reduce boilerplate. It is ESM-only and uses the native browser WebSocket API.

storage

npm install maxsocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MAXSOCKET

maxsocket

storagejavascriptv1.0.2

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.

connect

✓ import { connect } from 'maxsocket'

✗ const connect = require('maxsocket')

ESM-only; CommonJS require will fail. Use dynamic import() in Node if necessary.

MaxSocket (type)

✓ import type { MaxSocket } from 'maxsocket'

✗ import { MaxSocket } from 'maxsocket'

MaxSocket is only a TypeScript type, not a runtime value.

MaxSocketOptions (type)

✓ import type { MaxSocketOptions } from 'maxsocket'

Named type import for TypeScript; not a runtime export.

This example demonstrates connecting to a WebSocket server, handling connection, receiving messages, and closing the socket.

import { connect } from 'maxsocket'; const ws = connect('wss://api.example.com', { reconnect: 3000, queue: true, params: { token: process.env.WS_TOKEN ?? '' } }); ws.onConnect(() => { console.log('Connected'); ws.send({ type: 'greeting', data: 'Hello' }); }); ws.onMessage((msg) => { console.log('Received:', msg); }); ws.onClose((event) => { console.log('Closed:', event.reason); }); setTimeout(() => ws.close(), 10000);

Debug

Known issues

gotchaThe library uses the native browser WebSocket API and does not support Node.js `ws` library.

fix

Use in browser environments only, or use a package like 'ws' directly for Node.js.

affects: >=1.0

gotchaThe `on('event', handler)` routing only works if the server sends messages shaped as `{ event: string, data: any }`. If the message format is different, `onMessage` will not be called.

fix

Ensure server messages follow the required format, or avoid using event routing and use `onMessage` directly.

affects: >=1.0

gotchaMessages sent via `socket.send()` are automatically JSON-stringified. If you send a string, it will be double-stringified.

fix

Only send objects as data; if you need to send raw strings, consider manual serialization.

affects: >=1.0

breakingVersion 1.0.0 marked the initial release; no breaking changes yet.

fix

No fix needed.

affects: >=1.0

Errors

Common errors & fixes

Uncaught ReferenceError: WebSocket is not defined

Running in a Node.js environment without a WebSocket implementation.

fix

Use in a browser or provide a global WebSocket polyfill (e.g., 'ws' library).

Module not found: Can't resolve 'maxsocket'

Package not installed or import path incorrect.

fix

Run `npm install maxsocket` and ensure the import is `import { connect } from 'maxsocket'`.

Unhandled Promise Rejection: TypeError: ws.send is not a function

Calling `connect` without awaiting or using the returned socket before connection.

fix

Use `onConnect` to send messages after connection is established.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/max-matinpalo/maxsocket ↗

packagemaxsocket ↗

homepagehttps://github.com/max-matinpalo/maxsocket#readme ↗