# SocketCluster: a Node.js pub/sub and RPC framework for multi-process realtime servers

> SocketCluster is a JavaScript toolset for building realtime pub/sub and RPC systems that scale across CPU cores and machines. Its CLI scaffolds a working server, but the details that matter live in the client and server repositories, not the README.

**SocketCluster/socketcluster** — Highly scalable realtime pub/sub and RPC framework

- Repository: https://github.com/SocketCluster/socketcluster
- Website: https://socketcluster.io
- Stars: 6,192 · Forks: 317
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/socketcluster-socketcluster

## The problem SocketCluster solves: realtime fan-out across more than one process

A single Node.js process handles one event loop. Once a realtime server needs to push messages to many connected clients, or run request/response handlers that take real work, one process stops being enough. SocketCluster is aimed at that point. The README describes it as a "Toolset and boilerplate for quickly creating systems using SocketCluster", and the package description in package.json calls it a "Highly scalable realtime framework with support for async/await". The repository topics include pubsub, websocket, kubernetes and docker, which matches the intended deployment shape: multiple worker processes behind a load balancer, coordinating through pub/sub channels and RPC calls.

The audience is Node.js engineers building chat, live dashboards, multiplayer state or internal event buses who expect to run more than one instance. It is not a general web framework and it is not a drop-in replacement for a plain WebSocket library. The README points elsewhere for the actual API documentation, which tells you where the project expects you to spend your time.

## How SocketCluster splits work: client, server and the SCC cluster guide

The README is explicit that the top-level repository is a toolset and boilerplate layer. Documentation for the two halves lives in separate repositories: socketcluster-client and socketcluster-server. A third document, scc-guide.md in this repository, covers SCC, described in the README as the "horizontally scalable cluster".

That layout implies the architecture. The server package attaches to an HTTP server and manages connections, channels and RPC. The client package connects, subscribes and invokes procedures. SCC is the part that coordinates multiple server instances so a message published on one process reaches subscribers on another. The README does not reproduce that guide, so the coordination mechanism itself has to be read from scc-guide.md rather than inferred from the README.

One compatibility detail is documented at the top level. For older clients, the server attach call takes a protocolVersion and a path, and the README states that protocolVersion must be set to 1 and path must match the old client path. This is the kind of setting that decides whether an upgrade is a deploy or an outage.

## Installing the socketcluster CLI and running a first server

Installation goes through npm. The README says to set up Node.js first, then install the socketcluster command globally, either with or without sudo. The package.json bin entry maps the socketcluster command to bin/cli.js, so the global install is what puts that command on your path.

```bash
npm install -g socketcluster
```

or, if your npm prefix needs elevated permissions:

```bash
sudo npm install -g socketcluster
```

With the CLI available, scaffold an application. The README uses myapp as the example name.

```bash
socketcluster create myapp
```

Enter the generated directory and start the server with node server, as the README shows.

```bash
cd myapp
node server
```

The README says the app is then reachable at http://localhost:8000/. Node.js v10.0.0 or above is recommended. The README adds a caveat for older runtimes: SocketCluster still works on them if you use while loops instead of for-await-of loops, which tells you the async iteration syntax is the part that requires the newer runtime.

For a first real use, the interesting file is not the scaffold but the server attach call. The README gives this compatibility example, which is also the shape of a normal attach:

```js
let agServer = socketClusterServer.attach(httpServer, {
  protocolVersion: 1,
  path: '/socketcluster/'
});
```

Setting protocolVersion to 1 is described as the compatibility mode for existing SocketCluster clients, and path must match the old client path. If you are starting fresh rather than migrating, the README does not spell out which values to use instead, so check the server repository before copying this block.

## Where SocketCluster gets awkward: thin top-level docs and a stalled release trail

The first limitation is documentation placement. The README for the repository you install from does not document the client API, the server API, channel semantics or RPC error handling. It redirects to two other repositories and to scc-guide.md. That is a reasonable split for maintainers, but it means a reader who lands on the main repository gets install steps and a compatibility snippet and little else. Anything about authentication, middleware, backpressure or reconnection has to be found in the client and server repositories.

The second limitation is version signalling. The most recent release listed for this repository is v17.3.1, dated 2023-03-11. The package.json in the repository declares version 20.1.0. The README's change log section points to the releases page for changes. A gap between the newest tagged release and the version in package.json is not proof of anything broken, but it does mean you should confirm which version a global npm install of socketcluster resolves to before you build on it. The last push to the repository was on 2026-08-21, so the codebase is not frozen, but the release list alone will not tell you what changed.

Third, the test script in package.json is a placeholder: it echoes an error and exits 1. There is no runnable test suite in this package. If your adoption process depends on running the project's own tests before trusting it, this repository will not satisfy that step.

Finally, SocketCluster is the wrong tool for a single-process service that only needs a WebSocket endpoint. The cluster coordination and pub/sub layers are overhead you would be paying for without using.

## SocketCluster versus Socket.IO: cluster coordination against a broad client ecosystem

Socket.IO is the obvious comparison, and the difference is in what each one optimises for. Socket.IO is a realtime library with a wide range of client implementations and a long list of transports and fallbacks. SocketCluster's distinguishing feature, based on the README and repository topics, is the clustered pub/sub and RPC model: SCC is documented separately as the horizontally scalable cluster, and the package keywords are socketcluster, async, await and realtime.

In practice, choosing Socket.IO usually means you accept a single-process model and add a separate pub/sub adapter when you outgrow it. Choosing SocketCluster means the multi-process story is the starting assumption, and the price is a smaller ecosystem and documentation spread across three repositories. If your team already knows Socket.IO and your traffic fits one process, switching buys you very little. If you are already partitioning connections across workers and hand-rolling cross-worker message routing, SocketCluster is designed for exactly that shape.

## Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-08-21, so work is still landing on the default branch. That said, the release list is sparse: v17.3.1 in 2023, v16.0.1 in 2020 and v14.3.0 in 2018. Anyone planning an upgrade should read the releases page, which the README names as the change log, rather than assuming the release cadence matches the commit cadence.

Upgrade cost concentrates in two places. The first is the protocolVersion and path pair shown in the README's compatibility mode section. Clients built against an older protocol need protocolVersion 1 and a matching path, so a server upgrade can strand connected clients if those values drift. The second is the Node.js baseline: v10.0.0 or above is recommended, and older runtimes require while loops instead of for-await-of. If you are pinned to an old Node.js version, that constraint shapes how much of the async API you can use.

The licence is MIT, stated in both the README and package.json, with copyright 2013-2023 SocketCluster.io. MIT permits use, modification, distribution and sublicensing provided the copyright notice and permission notice are included, and it disclaims warranty. That is a permissive arrangement typical of Node.js tooling, but it is not legal advice; if your organisation has licence review requirements, route the LICENSE file through it.

## Conclusion

Adopt SocketCluster when you need realtime pub/sub and RPC across multiple Node.js processes or hosts and you are willing to read the client and server repositories for the API. Do not adopt it if you want a single-process WebSocket library with everything documented in one place, or if you need the CLI itself to be actively developed: the last push to the repository was on 2026-08-21, but the most recent release listed is v17.3.1 from 2023-03-11 while package.json declares version 20.1.0. Before committing, verify the protocolVersion and path settings against your existing clients, and confirm which version the socketcluster command actually installs.

## FAQ

### What is SocketCluster?

SocketCluster is a JavaScript toolset and boilerplate for creating realtime systems, described in package.json as a highly scalable realtime framework with support for async/await. The README splits the documentation between the socketcluster-client and socketcluster-server repositories, with a separate guide for SCC, the horizontally scalable cluster.

### How do I install SocketCluster?

Set up Node.js first, then run npm install -g socketcluster (or sudo npm install -g socketcluster). After that, the README shows socketcluster create myapp to scaffold an application, and node server inside the generated directory to launch it.

### Where does a SocketCluster server run by default?

The README states that after running node server in the generated myapp directory, the app is accessible at http://localhost:8000/.

### Which Node.js version does SocketCluster need?

Node.js v10.0.0 or above is recommended. The README notes that older Node.js versions still work if you use while loops instead of for-await-of loops.

### How do I keep older SocketCluster clients working after a server change?

The README's compatibility mode section says to set protocolVersion to 1 in the socketClusterServer.attach options and make sure path matches your old client path, using '/socketcluster/' in its example.

## Sources

- [License: MIT](https://github.com/SocketCluster/socketcluster/blob/master/LICENSE)
- [Project website](https://socketcluster.io)
- [README](https://github.com/SocketCluster/socketcluster/blob/master/README.md)
- [Releases](https://github.com/SocketCluster/socketcluster/releases)
- [SocketCluster/socketcluster on GitHub](https://github.com/SocketCluster/socketcluster)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/socketcluster-socketcluster