How cluster module works in Node.js

Introduction

The cluster module helps Node.js use multiple CPU cores to run tasks faster by creating copies of the main program.

When you want your Node.js app to handle many users at the same time without slowing down.

When your server has multiple CPU cores and you want to use them all efficiently.

When you want to keep your app running even if one part crashes by restarting workers.

When you want to balance the load of incoming requests across several processes.

Syntax

Node.js

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

if (cluster.isPrimary) {
  const cpuCount = os.cpus().length;
  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }

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

cluster.isPrimary checks if the current process is the main one that controls workers.

cluster.fork() creates a new worker process that runs the same code.

Examples

This example creates one worker per CPU core. Each worker runs a simple HTTP server.

Node.js

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

if (cluster.isPrimary) {
  const cpuCount = os.cpus().length;
  for (let i = 0; i < cpuCount; i++) {
    cluster.fork();
  }
} else {
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('Hello from worker ' + process.pid);
  }).listen(8000);
}

This example creates exactly two worker processes that print their process IDs.

Node.js

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  cluster.fork();
  cluster.fork();
} else {
  console.log('Worker ' + process.pid + ' started');
}

Sample Program

This program uses the cluster module to create one worker per CPU core. The primary process manages workers and restarts any that die. Each worker runs a simple HTTP server that responds with its process ID.

Node.js

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

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

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

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died. Restarting...`);
    cluster.fork();
  });
} else {
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Hello from worker ${process.pid}`);
  }).listen(8000);
  console.log(`Worker ${process.pid} started and listening on port 8000`);
}

Important Notes

Workers share the same server port but run in separate processes, improving performance on multi-core machines.

If a worker crashes, the primary process can restart it automatically to keep the app running smoothly.

Use cluster only when your app is CPU-bound or needs to handle many connections simultaneously.

Summary

The cluster module lets Node.js use all CPU cores by creating worker processes.

The primary process controls workers and can restart them if they crash.

Workers run the same code and can share server ports to handle many requests efficiently.

Practice

1. What is the main purpose of the cluster module in Node.js?

easy

A. To provide a graphical user interface for Node.js apps

B. To manage database connections efficiently

C. To handle file system operations asynchronously

D. To create multiple worker processes to use all CPU cores

Solution

1. Step 1: Understand the cluster module role

   The cluster module allows Node.js to create multiple worker processes.

2. Step 2: Recognize the benefit

   These workers use all CPU cores to improve performance by handling requests in parallel.

3. Final Answer:

   To create multiple worker processes to use all CPU cores -> Option D

4. Quick Check:

   cluster module = multiple workers for CPU cores [OK]

Hint: Cluster = multiple processes for CPU cores [OK]

Common Mistakes:

• Confusing cluster with database or file system modules
• Thinking cluster manages UI or frontend
• Assuming cluster runs code in a single process

2. Which of the following is the correct way to check if the current process is the master in a cluster setup?

easy

A. if (cluster.isMaster) { ... }

B. if (cluster.isPrimary) { ... }

C. if (cluster.isWorker) { ... }

D. if (cluster.isMain) { ... }

Solution

1. Step 1: Recall the updated property name

   In recent Node.js versions, cluster.isPrimary replaces cluster.isMaster.

2. Step 2: Identify the correct syntax

   Using cluster.isPrimary correctly checks if the process is the primary (master) process.

3. Final Answer:

   if (cluster.isPrimary) { ... } -> Option B

4. Quick Check:

   Primary process check = cluster.isPrimary [OK]

Hint: Use cluster.isPrimary, not isMaster [OK]

Common Mistakes:

• Using deprecated cluster.isMaster instead of cluster.isPrimary
• Confusing isWorker with isPrimary
• Using non-existent properties like isMain

3. Consider this Node.js cluster code snippet:

const cluster = require('cluster');
const http = require('http');

if (cluster.isPrimary) {
  cluster.fork();
  cluster.fork();
} else {
  http.createServer((req, res) => {
    res.end('Worker ' + process.pid);
  }).listen(8000);
}

What will happen when you visit http://localhost:8000 multiple times?

medium

A. You will see responses from different worker process IDs

B. Only one worker will handle all requests

C. The server will crash because of multiple forks

D. You will get a syntax error on startup

Solution

1. Step 1: Understand cluster.fork creates workers

   Two workers are created, each running the HTTP server on port 8000.

2. Step 2: Recognize load balancing behavior

   Requests are distributed between workers, so responses show different process IDs.

3. Final Answer:

   You will see responses from different worker process IDs -> Option A

4. Quick Check:

   Multiple workers share port, respond with different PIDs [OK]

Hint: Multiple forks = multiple workers respond differently [OK]

Common Mistakes:

• Thinking only one worker handles all requests
• Assuming server crashes due to multiple forks
• Expecting syntax errors from this code

4. What is wrong with this cluster code snippet?

const cluster = require('cluster');
if (cluster.isPrimary) {
  cluster.fork();
} else {
  console.log('Worker running');
}

medium

A. cluster.isPrimary is deprecated, should use isMaster

B. No call to cluster.fork in the worker process

C. Missing server code inside worker

D. No error, code works fine

Solution

1. Step 1: Check cluster usage

   The primary forks one worker, which only logs a message but does not start a server.

2. Step 2: Identify missing functionality

   Without server code, the worker does not handle requests, so the cluster setup is incomplete.

3. Final Answer:

   Missing server code inside worker -> Option C

4. Quick Check:

   Worker must run server code to handle requests [OK]

Hint: Workers need server code to handle requests [OK]

Common Mistakes:

• Confusing isPrimary with deprecated isMaster
• Expecting cluster.fork in worker process
• Assuming code runs without server in worker

5. You want to create a cluster that automatically restarts a worker if it crashes. Which approach correctly implements this behavior?

hard

A. Listen to the 'exit' event on cluster and fork a new worker inside the handler

B. Use setInterval to fork new workers every second

C. Call cluster.fork() only once at startup and never again

D. Use cluster.disconnect() inside the worker to restart itself

Solution

1. Step 1: Understand worker crash handling

   The primary process can listen to the 'exit' event when a worker dies.

2. Step 2: Restart worker on exit

   Inside the 'exit' event handler, calling cluster.fork() creates a new worker to replace the crashed one.

3. Final Answer:

   Listen to the 'exit' event on cluster and fork a new worker inside the handler -> Option A

4. Quick Check:

   Restart crashed workers by handling 'exit' event [OK]

Hint: Use 'exit' event to restart workers automatically [OK]

Common Mistakes:

• Forking workers repeatedly with setInterval causes overload
• Not restarting workers after crash leads to downtime
• Using cluster.disconnect() inside worker does not restart it