Registry / http-networking / socketcluster-client

socketcluster-client

JSON →
library20.0.1jsnpmunverified

SocketCluster Client (socketcluster-client) is the JavaScript client library for connecting to SocketCluster servers, enabling high-performance, real-time, bi-directional communication over WebSockets. It provides abstractions for pub/sub (channels), remote procedure calls (RPC), and efficient data streaming. The library is currently at version 20.0.1, indicating an active development cycle with frequent major releases that often introduce breaking changes. Key differentiators include its focus on scalability, built-in support for backpressure handling, and a clear API for consuming events and data streams using async iterators, making it suitable for demanding real-time applications like chat, gaming, and financial dashboards. It is designed to work seamlessly with `socketcluster-server`.

npm install socketcluster-client
INSTALL
IMPORT
SIG · SOCKETCLUSTER-CLIE
S
socketcluster-client
http-networkingjavascriptv20.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

create
import { create } from 'socketcluster-client';
import socketClusterClient from 'socketcluster-client'; const socket = socketClusterClient.create(...);
Since v10.0.0, `create` is the preferred named export for initiating a connection. The default export is often used but less precise.
SCClientSocket
import { SCClientSocket } from 'socketcluster-client';
import { SCSocket } from 'socketcluster-client';
The primary socket class was renamed from `SCSocket` to `SCClientSocket` in v13.0.0 for clarity and consistency. Use `SCClientSocket` for type imports or direct instantiation.
socketClusterClient (global/module object)
const socketClusterClient = require('socketcluster-client'); // CommonJS // Or in browser after script tag: const socket = socketClusterClient.create(...);
import socketClusterClient from 'socketcluster-client'; // Potentially not the default export, depending on bundler config.
The module's main export is often an object containing utility methods like `create`. In browsers, a global `socketClusterClient` object is available after loading the script.

Demonstrates connecting to a SocketCluster server, transmitting data, invoking an RPC, subscribing to a channel, publishing to it, and consuming messages using async iterators.

import { create } from 'socketcluster-client'; const socket = create({ hostname: 'localhost', port: 8000, autoConnect: true, autoReconnectOptions: { initialDelay: 1000, randomness: 500, multiplier: 1.2, maxDelay: 10000 } }); (async () => { try { await socket.listener('connect').once(); console.log('Socket connected successfully to server.'); // Transmit data to the server without expecting a response socket.transmit('chatMessage', { user: 'developer', text: 'Hello SocketCluster!' }); // Invoke a remote procedure call (RPC) and await a response const serverTime = await socket.invoke('getServerTime'); console.log('Server time received:', serverTime); // Subscribe to a channel and consume messages const myChannel = socket.subscribe('myPublicChannel'); await myChannel.listener('subscribe').once(); console.log('Successfully subscribed to channel: myPublicChannel'); // Publish a message to the channel await myChannel.invokePublish('This is a message from the client.'); console.log('Published message to channel.'); // Consume messages from the channel using an async iterator for await (const data of myChannel) { console.log('Received channel message:', data); // For demonstration, process one message then unsubscribe break; } myChannel.unsubscribe(); console.log('Unsubscribed from channel.'); } catch (error) { console.error('Socket error or connection failed:', error); } // Disconnect the socket after a short delay setTimeout(() => { socket.disconnect(); console.log('Socket disconnected.'); }, 5000); })();
Debug
Known issues
breakingThe `SCSocket` class was renamed to `SCClientSocket` for better clarity and consistency with server-side naming conventions.
fix
Update all references from `SCSocket` to `SCClientSocket` in your code, including type imports and class instantiations.
affects: >=13.0.0
breakingThe 'authenticate' event now triggers whenever the `authToken` changes, not just on the initial authentication. This affects scenarios where a new user's token might override a previously logged-in user's token on the same client instance.
fix
Review event handlers for 'authenticate' to ensure they correctly handle token changes and potential user session overrides, especially in multi-user or shared device environments.
affects: >=12.0.0
breakingThe `socketCluster.connect(options)` method was renamed to `socketCluster.create(options)`. The `connect` alias is deprecated but still available.
fix
Replace `socketClusterClient.connect(...)` with `socketClusterClient.create(...)` or `create(...)` if using named imports. While `connect` might still work, it is deprecated.
affects: >=10.0.0
breakingThe `socketCluster.connections` object/map was renamed to `socketCluster.clients`.
fix
Update any references to `socketCluster.connections` to `socketCluster.clients`.
affects: >=10.0.0
gotchaPassing invalid combinations of `hostname`, `host`, and `port` arguments to `create()` will now throw an error, enforcing stricter configuration validation.
fix
Ensure that connection options (hostname, host, port) are correctly configured and mutually exclusive where required. Refer to the official documentation for valid combinations.
affects: >=11.0.0
gotchaAttempting to emit a reserved event on the socket will now cause an error to be emitted on the socket itself. This prevents potential conflicts with internal SocketCluster protocols.
fix
Avoid using event names that are internally reserved by SocketCluster for custom transmissions. If an error is triggered, rename your custom event.
affects: >=13.0.0
Errors
Common errors & fixes
TypeError: socketCluster.connect is not a function
Using the deprecated `connect` method instead of `create`.
fix
Change `socketClusterClient.connect(...)` to `socketClusterClient.create(...)`. The `connect` method was renamed in v10.0.0.
ReferenceError: socketClusterClient is not defined
The `socketcluster-client` script tag was not loaded in the HTML, or the module was not correctly imported/required in a module environment.
fix
Ensure `<script type="text/javascript" src="/socketcluster-client.js"></script>` is present and accessible in your HTML, or use `import { create } from 'socketcluster-client';` (ESM) / `const { create } = require('socketcluster-client');` (CJS) at the top of your JavaScript file.
Error: Cannot read properties of undefined (reading 'connections')
Attempting to access `socketCluster.connections` which was renamed.
fix
Update code to use `socketCluster.clients` instead of `socketCluster.connections`. This rename occurred in v10.0.0.
UnhandledPromiseRejectionWarning: Error: Socket emitted a reserved event
The client attempted to emit an event name that is reserved by SocketCluster internally.
fix
Rename the custom event you are trying to transmit to avoid conflict with SocketCluster's internal event names. This behavior changed in v13.0.0.
Upgrade
Version history
20.0.1latest on npm
Audit
Dependencies
socketcluster-serveroptionalRequired to run a complete SocketCluster application. The client connects to a server instance provided by this package.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
socketcluster-client — npm install socketcluster-client · libregistry