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.
import cluster from "node:cluster"; if (cluster.isPrimary) { cluster.fork(); } else { // worker code }
Try it
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.
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
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
isPrimarytoisMaster. 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
ifruns 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.jsis 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, andisPrimarystaystruein it unlessNODE_UNIQUE_IDwas 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.