Stop 02 · Node.js FundamentalsTopics · 18/18

Clustering

In short

Your machine has several CPU cores, but one Node process runs your JavaScript on just one of them. Clustering starts a worker per core so one machine serves far more requests.

Node's built-in module for spawning multiple worker processes that share the same server port, letting a single-threaded runtime take advantage of multi-core machines.

The mascot directs a crowd of travellers with suitcases towards several identical ticket windows.

Think of it like this

More ticket windows at Diwali

During the festival rush, the station doesn't make one clerk work faster. It opens more identical windows, and a supervisor sends each traveller to a free one. If a clerk falls sick, a new one takes the seat. That's clustering: same code, many workers, one entrance.

Watch it happen

A primary and two workers

Clients

Primary

Worker 1

Worker 2

fork()

1/8The primary process starts and forks a worker, usually one per CPU core.

The big ideas

What you need to know

One worker per core

os.availableParallelism() tells you how many workers make sense on this machine.

No shared memory

Workers are separate processes. Sessions, counters and caches must live in Redis or a database.

Self-healing

Listen for 'exit' in the primary and fork a new worker, so one crash doesn't take the app down.

Often done for you

Tools like PM2, or running several containers behind a load balancer, give the same benefit without writing cluster code.

See it in code

Walk through the code

1import cluster from "node:cluster";2import http from "node:http";3import { availableParallelism } from "node:os";4 5if (cluster.isPrimary) {6  for (let i = 0; i < availableParallelism(); i++) cluster.fork();7  cluster.on("exit", (worker) => {8    console.log(`worker ${worker.process.pid} died, starting a new one`);9    cluster.fork();10  });11} else {12  http.createServer((req, res) => {13    res.end(`handled by ${process.pid}\n`);14  }).listen(3000);15}

1/3The primary only manages. It forks one worker per available core.

Run it and curl localhost:3000 a few times: different PIDs answer. Kill one worker with kill and its pid, and watch the primary replace it.

Save yourself the pain

Common mistakes

Oops

Keeping sessions or counters in a variable and expecting every worker to see it.

Do this instead

Each worker has its own memory. Put shared state in Redis or a database.

Oops

Expecting clustering to speed up one slow, CPU-heavy request.

Do this instead

Each request still runs on one worker. Clustering adds capacity, not speed per request. Use worker_threads to split heavy work.

Your mission

Scale on your laptop

~25 min

Quick check

Two cluster workers each keep let visits = 0 and add one per request. After 10 requests, what does each worker report?

Go deeper

1Set up a basic cluster that forks one worker per CPU core.
2Learn how the cluster module load-balances incoming connections across workers.
3Compare clustering to using a process manager like PM2's built-in cluster mode.