Node.js Clustering

Why Clustering Exists

Even though Node.js is efficient at handling many concurrent I/O-bound connections on a single thread, that single thread still only uses one CPU core. On a machine with 8 cores, a single Node.js process leaves 7 of them idle. Clustering spawns multiple worker processes, each with its own event loop, sharing the same server port, so incoming connections are distributed across all available cores.

The cluster module implements a primary/worker model: one "primary" process forks several "worker" processes and load-balances incoming connections between them, all while presenting a single listening port to the outside world.

import cluster from 'node:cluster';
import os from 'node:os';
import http from 'node:http';

if (cluster.isPrimary) {
  const cpuCount = os.cpus().length;
  console.log(`Primary process forking ${cpuCount} workers`);

  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }
} else {
  http.createServer((req, res) => {
    res.end(`Handled by worker ${process.pid}`);
  }).listen(3000);
}

Every worker process runs this same file, cluster.isPrimary distinguishes the coordinating primary process from each individual worker.

Cluster Module Basics

cluster.isPrimary          // true only in the primary process
cluster.fork()              // spawn a new worker process
cluster.on('exit', (worker) => { ... })  // detect a worker dying

• cluster.isPrimary (formerly isMaster) distinguishes the coordinating process from workers.
• Each worker is a fully separate Node.js process with its own memory and event loop.
• The primary process automatically load-balances incoming connections across workers on most platforms.
• Workers can crash independently without taking down the primary process or other workers.

Clustering Cheatsheet

Key concepts in Node's primary/worker clustering model.

Restarting Crashed Workers Automatically

One major benefit of clustering beyond raw CPU utilization is fault isolation: if a worker crashes due to an unexpected error, the primary process can detect the 'exit' event and immediately fork a replacement, keeping the overall service available.

cluster.on('exit', (worker, code, signal) => {
  console.log(`Worker ${worker.process.pid} died, restarting...`);
  cluster.fork();
});

cluster Module vs Process Managers

The built-in cluster module works well, but production deployments often instead rely on a dedicated process manager (like PM2) or container orchestration (like Kubernetes) to handle multi-instance scaling, restarts, and zero-downtime deploys, sometimes layered on top of cluster itself, sometimes replacing it entirely.

Common Mistakes

• Assuming clustered workers share memory, they're fully separate processes; shared state needs an external store (like Redis).
• Not handling the 'exit' event to restart crashed workers automatically.
• Running as many workers as CPU cores while also running other CPU-intensive processes on the same machine.
• Reaching for manual clustering when a process manager or container orchestrator already handles this at the infrastructure level.

Key Takeaways

• Clustering spawns multiple worker processes to use all available CPU cores for one server.
• Each worker is a separate process with its own memory, they don't share state automatically.
• The primary process can detect crashed workers and restart them, improving fault tolerance.
• Many production setups rely on process managers or orchestration tools instead of, or alongside, manual clustering.