cluster — Multi-core

Using all CPU cores in Node.js — the cluster module, worker processes, load balancing, and when to use cluster vs worker_threads.

What it is, in plain English: Node.js runs on a single thread by default — it can only use one CPU core. The cluster module lets you spawn multiple worker processes that all share the same port. The primary process manages the workers; workers handle incoming requests. The OS distributes connections across workers (round-robin on Linux/Mac). For CPU-bound work, use worker_threads. For I/O-bound servers, use cluster.

Using all CPU cores

Node.js uses one CPU core by default. If your server has 8 cores, 7 are idle. The cluster module creates multiple worker processes, each handling requests independently. The OS distributes incoming connections between them.

import cluster   from "cluster";
import { cpus }  from "os";
import { createServer } from "http";

const numCPUs = cpus().length;  // 4, 8, 16 — depends on hardware

if (cluster.isPrimary) {
  // This code runs in the primary (manager) process:
  console.log(`Forking ${numCPUs} workers`);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();  // spawn one worker per CPU
  }

  cluster.on("exit", (worker, code) => {
    console.log(`Worker ${worker.process.pid} died. Restarting...`);
    cluster.fork();  // auto-restart crashed workers
  });

} else {
  // This code runs in EACH worker process:
  createServer((req, res) => {
    res.end(`Hello from worker ${process.pid}!`);
  }).listen(3000);
  // All workers share port 3000 — OS routes connections between them
}

Cluster vs worker_threads

cluster

worker_threads

Isolation

Separate processes

Same process

Memory

Separate heaps

Shared memory possible

Crash impact

One worker only

Whole process

Port sharing

Yes — OS distributes

Best for

HTTP servers, I/O-bound

CPU-heavy computation

Try It Yourself

// cluster — use all CPU cores for HTTP servers
// Node.js is single-threaded but you can run multiple processes

// import cluster from "cluster";
// import { cpus } from "os";
// import { createServer } from "http";

const CLUSTER_CODE = `
import cluster from "cluster";
import { cpus }  from "os";
import { createServer } from "http";

const numCPUs = cpus().length;

if (cluster.isPrimary) {
  // ── PRIMARY PROCESS ────────────────────────────────────────────────────
  console.log(\`Primary PID \${process.pid} — forking \${numCPUs} workers\`);

// Fork one worker per CPU:
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

// Restart workers if they crash:
  cluster.on("exit", (worker, code, signal) => {
    console.log(\`Worker \${worker.process.pid} died (code \${code}). Restarting...\`);
    cluster.fork();
  });

// Graceful shutdown:
  process.on("SIGTERM", () => {
    console.log("Graceful shutdown...");
    for (const worker of Object.values(cluster.workers)) {
      worker.send("shutdown");
    }
  });

} else {
  // ── WORKER PROCESS ─────────────────────────────────────────────────────
  const server = createServer((req, res) => {
    res.writeHead(200);
    res.end(\`Hello from worker \${process.pid}\`);
  });

server.listen(3000, () => {
    console.log(\`Worker \${process.pid} listening on port 3000\`);
  });

// Graceful shutdown for this worker:
  process.on("message", (msg) => {
    if (msg === "shutdown") {
      server.close(() => process.exit(0));
    }
  });
}
`;

// Show CPU count and what we'd fork:
const cpuCount = navigator.hardwareConcurrency || 4;
console.log(\`This device has \${cpuCount} logical CPU cores\`);
console.log(\`cluster.fork() would create \${cpuCount} worker processes\`);
console.log(\`Each handles requests independently on the same port\`);
console.log("\ncluster vs worker_threads:");
console.log("  cluster        — separate processes, for HTTP servers, I/O-bound");
console.log("  worker_threads — shared memory, for CPU-bound computation");
console.log("  pm2            — production process manager, handles cluster + restarts");

console.log("\nCluster server code:");
console.log(CLUSTER_CODE.slice(0, 400) + "...");

Graceful restart and pm2

// Graceful restart — reload workers one at a time (zero downtime):
// Send signal: kill -USR2 <primary_pid>

if (cluster.isPrimary) {
  const workers = new Set();

  const fork = () => {
    const w = cluster.fork();
    workers.add(w);
    w.on("exit", () => workers.delete(w));
    return w;
  };

  for (let i = 0; i < cpus().length; i++) fork();

  process.on("SIGUSR2", () => {
    console.log("Rolling restart...");
    const current = [...workers];
    let i = 0;

    function restartNext() {
      if (i >= current.length) return;
      const old = current[i++];
      const newWorker = fork();
      newWorker.once("listening", () => {
        old.send("shutdown");
        old.once("exit", restartNext);
      });
    }
    restartNext();
  });
}

// Worker handles shutdown:
process.on("message", (msg) => {
  if (msg === "shutdown") {
    server.close(() => process.exit(0));
  }
});

pm2 — the production alternative

// pm2 handles clustering, restarts, logs, and monitoring for you:
// npm install -g pm2

// Start with cluster mode (all cores):
// pm2 start app.js -i max  # max = number of CPUs

// pm2 ecosystem file (ecosystem.config.js):
// module.exports = {
//   apps: [{
//     name:      "api-server",
//     script:    "./server.js",
//     instances: "max",        // or a specific number
//     exec_mode: "cluster",
//     env: { NODE_ENV: "production", PORT: 3000 },
//   }]
// };

// Commands:
// pm2 start ecosystem.config.js
// pm2 reload api-server   ← zero-downtime restart
// pm2 logs api-server     ← tail logs
// pm2 monit               ← live dashboard

Connection distribution and cluster spec

// How connections are distributed:
// Linux/macOS: round-robin (primary assigns connections to workers)
// Windows: workers compete for connections (OS handles it)

// The scheduling policy:
import cluster from "cluster";
cluster.schedulingPolicy = cluster.SCHED_RR;   // round-robin (default on non-Windows)
// cluster.SCHED_NONE — OS decides (default on Windows)

// Primary ↔ Worker communication:
if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.send({ type: "config", value: { rateLimit: 100 } });
  worker.on("message", (msg) => console.log("Worker says:", msg));
} else {
  process.on("message", (msg) => {
    if (msg.type === "config") applyConfig(msg.value);
    process.send({ type: "ack", received: msg.type });
  });
}

// Worker suicide prevention:
cluster.on("exit", (worker) => {
  if (worker.exitedAfterDisconnect) {
    console.log("Worker intentionally stopped");
  } else {
    console.log("Worker crashed — restarting");
    cluster.fork();
  }
});

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.