Registry / http-networking / socketcluster-server

socketcluster-server

JSON →
library20.0.0jsnpmunverified

SocketCluster Server (version 20.0.0) is the core server-side module for the SocketCluster real-time framework, designed to facilitate highly scalable, event-driven applications using WebSockets. It operates by attaching to an existing Node.js HTTP/HTTPS server and provides robust mechanisms for managing inbound connections, handling Remote Procedure Calls (RPCs), and processing real-time event streams. A key differentiator and architectural shift in recent major versions is its adoption of modern JavaScript async iterators (`for-await-of` loops) for stream processing, moving away from traditional `EventEmitter` patterns. This paradigm promotes more readable, succinct, and less error-prone code by reducing callback hell and simplifying resource management, as listeners do not need explicit unbinding. While it maintains a compatibility mode for older clients (protocolVersion 1), the current stable version encourages the use of its async iterable API. Releases tend to align with major Node.js LTS updates or significant architectural improvements.

http-networkingweb-framework
npm install socketcluster-server
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · SOCKETCLUSTER-SERV
S
socketcluster-server
http-networkingjavascriptv20.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

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

socketClusterServer
✓ const socketClusterServer = require('socketcluster-server');
✗ import socketClusterServer from 'socketcluster-server';
Primary CommonJS import. For ESM, use `import * as socketClusterServer from 'socketcluster-server';` as the package exports an object. Direct `import socketClusterServer from 'socketcluster-server';` may not work as expected without a default export.
AGServer
✓ import type { AGServer } from 'socketcluster-server';
✗ import { AGServer } from 'socketcluster-server';
Type import for the `agServer` instance returned by `attach()`. Used for TypeScript type-checking to ensure correct API usage.
AGSocket
✓ import type { AGSocket } from 'socketcluster-server';
✗ import { AGSocket } from 'socketcluster-server';
Type import for individual `socket` instances obtained from `agServer.listener('connection')`. Essential for TypeScript type-checking when handling socket events.

Demonstrates how to attach SocketCluster server to an HTTP server and handle inbound connections, RPC procedures, and remote events using async iterators. It also shows transmitting a basic event to connected clients.

const http = require('http'); const socketClusterServer = require('socketcluster-server'); let httpServer = http.createServer(); let agServer = socketClusterServer.attach(httpServer); (async () => { // Handle new inbound sockets. for await (let {socket} of agServer.listener('connection')) { (async () => { // Set up a loop to handle and respond to RPCs for a procedure. for await (let req of socket.procedure('customProc')) { if (!req.data) { let error = new Error('Server failed to execute the procedure'); error.name = 'BadCustomError'; req.error(error); } else { req.end('Success'); } } })(); (async () => { // Set up a loop to handle remote transmitted events. for await (let data of socket.receiver('customRemoteEvent')) { console.log(`Received customRemoteEvent: ${data}`); } })(); socket.transmit('helloClient', { message: 'Hello from server!' }); } })(); httpServer.listen(8000, () => { console.log('SocketCluster Server listening on port 8000'); });
Debug
Known issues
breakingUpgrading from SocketCluster Server v15.x or earlier to v16.x and above (including v20.0.0) involves a significant API shift from `EventEmitter` patterns to async iterators (`for-await-of` loops). Code relying on `on()`, `addListener()`, or `removeListener()` will need to be refactored.
fix
Migrate event handling logic to use `for await (const { socket } of agServer.listener('connection'))` and `for await (let req of socket.procedure('procName'))` patterns. Refer to the official v16.x documentation on socketcluster.io.
affects: >=16.0.0
gotchaTo ensure compatibility with older SocketCluster clients (e.g., those using `socketcluster-client` v14.x or earlier), you must explicitly set `protocolVersion: 1` and potentially `path: '/socketcluster/'` during server attachment. Failure to do so will result in client connection errors.
fix
Configure `agServer` attachment with compatibility options: `let agServer = socketClusterServer.attach(httpServer, { protocolVersion: 1, path: '/socketcluster/' });`
affects: >=16.0.0
gotchaWhile `socketcluster-server` can operate independently, a complete real-time application setup typically requires `socketcluster-client` for browser or Node.js clients to connect and interact. For development and testing, both packages are generally needed to form a functional system.
fix
Install both packages: `npm install socketcluster-server socketcluster-client` and refer to `socketcluster-client` documentation for client-side setup.
affects: >=16.0.0
gotchaSocketCluster Server heavily leverages modern JavaScript features like `async/await` and `for-await-of` loops. Ensure your Node.js environment is sufficiently recent (e.g., Node.js 12+ for full compatibility) to avoid syntax errors or unexpected behavior.
fix
Use a recent LTS version of Node.js (e.g., Node.js 18 or 20) to ensure full compatibility with the async iterator paradigm and performance benefits.
affects: >=16.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require` syntax in an ES Module context without proper configuration.
fix
If running in an ES Module environment (e.g., `"type": "module"` in `package.json`), change import statements to `import * as socketClusterServer from 'socketcluster-server';` or configure your build tool for CommonJS compatibility.
Client failed to connect: Invalid protocol version
The client is attempting to connect using an older SocketCluster protocol version, but the server is expecting a newer one (or vice-versa).
fix
Enable compatibility mode on the server: `socketClusterServer.attach(httpServer, { protocolVersion: 1 });` or update your client to use a compatible `socketcluster-client` version and its default protocol.
TypeError: agServer.listener is not a function
This error likely indicates that `agServer` was not correctly initialized, or an incorrect method name was called, possibly due to an API change in major versions.
fix
Ensure `agServer` is correctly created using `socketClusterServer.attach(httpServer);` and that you are using the `listener()` method as shown in the v16+ documentation for async iterators.
Error: listen EADDRINUSE: address already in use :::8000
The specified port (e.g., 8000) for the HTTP server is already in use by another process or a previous instance of the server was not properly shut down.
fix
Change the `httpServer.listen()` port to an available one, or ensure no other applications are using the desired port. On Linux, `lsof -i :8000` can identify the process to terminate.
Upgrade
Version history
20.0.0latest on npm
Audit
Dependencies
socketcluster-clientrequiredRequired for a full client-server SocketCluster setup and for testing client interactions.
httprequiredRequired as a base HTTP server to which SocketCluster Server attaches.
httpsoptionalOptional, but commonly used as a base HTTPS server to which SocketCluster Server attaches for secure connections.
Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
githubhttps://github.com/SocketCluster/socketcluster-server ↗
packagehttps://www.npmjs.com/package/socketcluster-server ↗
homepagehttps://socketcluster.io/ ↗