Load balancing between workers in Node.js

Introduction

Load balancing helps spread tasks evenly across multiple workers so no single worker gets overwhelmed. This keeps your app fast and stable.

When your Node.js app needs to handle many requests at the same time.

When you want to use all CPU cores to improve performance.

When you want to avoid one worker crashing and stopping the whole app.

When you want to improve reliability by restarting workers if they fail.

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, code, signal) => {
    console.log(`Worker ${worker.process.pid} died. Restarting...`);
    cluster.fork();
  });
} else {
  // Worker code here
  // For example, start an HTTP server
}

Use cluster.isPrimary to check if the code runs in the main process.

Use cluster.fork() to create a new worker process.

Examples

This example creates one worker and logs a message from it.

Node.js

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

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

This example creates one worker per CPU core to balance load.

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();
  }
} else {
  // Worker code
}

This listens for worker exit events and restarts the worker automatically.

Node.js

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

Sample Program

This program uses the cluster module to create one worker per CPU core. Each worker runs an HTTP server on port 8000. When you visit localhost:8000, the response shows which worker handled your request. If a worker crashes, the primary process restarts it automatically.

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(`Handled by worker ${process.pid}\n`);
  }).listen(8000);

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

Important Notes

Each worker runs independently and can handle requests simultaneously.

Use the cluster module only in the main entry file of your app.

Restarting workers on exit helps keep your app reliable.

Summary

Load balancing spreads work across CPU cores using workers.

The cluster module helps create and manage worker processes.

Workers can be restarted automatically if they crash.