Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js cluster.isPrimary property

Reference for cluster.isPrimary and cluster.isWorker in Node.js: how one script branches into primary and worker code, the deprecated isMaster alias and pitfalls.

cluster.isPrimary is a boolean that is true in the process that started the cluster and false in every worker created by cluster.fork(). Its counterpart cluster.isWorker is the exact opposite. Together they let one script behave differently depending on which role the current process has.

Because a worker is started by running the same entry file again, the file needs this check. The primary branch forks workers and supervises them; the worker branch creates the server or does the job.

NODE
import cluster from "node:cluster";

if (cluster.isPrimary) {
  cluster.fork();
} else {
  // worker code
}

Try it

Node.js One script, two roles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Code outside the branch runs everywhere

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
cluster.isPrimary: boolean
cluster.isWorker: boolean
cluster.isMaster: boolean   // deprecated alias of isPrimary
cluster.worker: cluster.Worker | undefined      // only in a worker
cluster.workers: { [id: number]: cluster.Worker } | undefined   // only in the primary
Name Description
isPrimary true in the primary process. A process is primary when NODE_UNIQUE_ID is not set in its environment.
isWorker true in a process started with cluster.fork().
isMaster Old name for isPrimary, kept for compatibility and deprecated.
worker In a worker: the Worker object describing itself (id, disconnect(), ...). undefined in the primary.
workers In the primary: a hash of living workers keyed by id. undefined in a worker.

Errors / edge cases: the values are fixed for the life of the process. A worker cannot become the primary. Workers do not have cluster.fork().

Usage notes

  • Prefer isPrimary to isMaster. The new name has been available since Node 16; the old one still works but is deprecated.
  • Put shared setup outside the branch with care. Anything outside the if runs once in the primary and once in every worker, including imports that open connections or read large files.
  • Do not start servers in the primary if workers serve requests: a listener in the primary would compete with the workers and bypass scheduling.
  • A process that is simply run with node app.js is primary, even if it never forks. Code written with this check therefore still works as a plain single process.
  • The check is environment-based. A manually started child (child_process.fork()) is not a cluster worker, and isPrimary stays true in it unless NODE_UNIQUE_ID was inherited.
  • Tests: keep the branching code small and put the real work in functions you can call directly, since forking in a test runner multiplies the test process.