Scaling Node.js with Cluster: Unlocking Multi-Core Performance

Mar 12, 2025

If you're running a high-traffic Node.js application, you've probably hit a bottleneck where a single process just isn’t enough. Since Node.js runs on a single thread, how do we take advantage of multi-core CPUs?

The answer: Clustering. 🚀

🔥 What is the Cluster Module?

The Cluster module in Node.js allows you to spawn multiple child processes (workers), each handling requests independently but sharing the same port.

Think of it as hiring multiple chefs in a kitchen instead of relying on just one. More workers = better performance! 💪

🛠 Basic Cluster Setup

Let’s set up a clustered Node.js server:

import cluster from "cluster";
import http from "http";
import os from "os";

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  console.log(`🚀 Master process ${process.pid} is running`);

  // Fork workers
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  // Restart workers if they die
  cluster.on("exit", (worker) => {
    console.log(`💀 Worker ${worker.process.pid} died. Spawning a new one...`);
    cluster.fork();
  });
} else {
  // Worker processes create HTTP server
  http
    .createServer((req, res) => {
      res.writeHead(200);
      res.end(`Handled by Worker ${process.pid}\n`);
    })
    .listen(3000);

  console.log(`⚡ Worker ${process.pid} started`);
}

🔍 What’s Happening?

  • The primary process (cluster.isPrimary) spawns workers = one per CPU core.
  • Each worker process creates an HTTP server.
  • If a worker crashes, the master replaces it.
  • All workers share the same port (3000).

⚡ Testing the Cluster

Run the server:

node cluster-server.mjs

Now open multiple terminal tabs and run:

curl http://localhost:3000

Each request gets handled by a different worker, proving we’re using multiple processes! 🚀

🔗 Worker Communication

Workers don’t share memory, but they can send messages to each other and the master.

Example: Worker sends a message to the master

if (cluster.isPrimary) {
  cluster.on("message", (worker, message) => {
    console.log(`📩 Message from Worker ${worker.process.pid}:`, message);
  });

  cluster.fork(); // Start a worker
} else {
  process.send({ status: "Hello from Worker!" });
}

Each worker can communicate with the master process, allowing coordination and data exchange.

🎯 Real-World Use Case: Scaling an API Server

Imagine you're running a REST API that serves thousands of requests per second.

Without clustering:

  • The Node.js process handles all requests alone, causing slow responses under high traffic.
  • Requests queue up, increasing latency.
  • CPU utilization is low because it only runs on a single core.

With clustering:

  • The API server spawns multiple workers, distributing the load.
  • More requests are handled in parallel, reducing response time.
  • CPU utilization increases, making the most of available resources.

How to Apply Clustering to an Express.js API

Let’s modify our setup to handle API requests using Express.js.

import cluster from "cluster";
import os from "os";
import express from "express";

const numCPUs = os.cpus().length;

if (cluster.isPrimary) {
  console.log(`🚀 Master ${process.pid} is running`);

  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on("exit", (worker) => {
    console.log(`💀 Worker ${worker.process.pid} died. Restarting...`);
    cluster.fork();
  });
} else {
  const app = express();

  app.get("/", (req, res) => {
    res.send(`Handled by Worker ${process.pid}`);
  });

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

Benefits

✅ Handles more concurrent requests – Each worker runs on a separate core.
✅ Prevents downtime – If a worker crashes, another takes over.
✅ Improves performance – Spreads workload across CPU cores.

🎯 Why Use Clustering?

  1. Maximizes CPU Utilization 🔥 → Run multiple Node.js instances on all cores.
  2. Handles More Requests 🚀 → Distributes load across multiple processes.
  3. Prevents Crashes 🛑 → If one worker dies, others keep running.
  4. Great for Scaling 📈 → Essential for high-traffic applications.

⚠️ Limitations of Clustering

  • Workers don’t share memory → Use databases (e.g., Redis) for shared state.
  • Not ideal for CPU-heavy tasks → Consider worker threads instead.
  • Limited scaling → For multiple servers, use load balancers (NGINX, PM2, Kubernetes).

🔥 Final Thoughts

The Cluster module is a simple and powerful way to scale Node.js applications. It’s perfect for handling high traffic and ensuring better fault tolerance.

diogoaoliveira.com