JavaScript runtimes use a single processing thread. The engine does one factor at a time and should full execution earlier than it could actually do the rest. This hardly ever causes issues in a browser, as a result of a single consumer interacts with the app. However Node.js apps could possibly be dealing with a whole lot of consumer requests. Multithreading can forestall bottlenecks in your app.

Think about a Node.js net utility the place a single consumer may set off a posh, ten-second JavaScript calculation. The app could be unable to deal with incoming requests from some other customers till that calculation completes.

Languages similar to PHP and Python are additionally single threaded, however they usually use a multi-threaded net server which launches a brand new occasion of the interpreter on each request. That is resource-intensive, so Node.js purposes typically present their very own light-weight net server.

A Node.js net server runs on a single thread, however JavaScript alleviates efficiency issues with its non-blocking occasion loop. Apps can asynchronously execute operations similar to file, database, and HTTP that run on different OS threads. The occasion loop continues and might deal with different JavaScript duties whereas it waits for I/O operations to finish.

Sadly, long-running JavaScript code — similar to picture processing — can hog the present iteration of the occasion loop. This text explains how you can transfer processing to a different thread utilizing:

Desk of Contents

Node.js Employee Threads

Worker threads are the Node.js equal of web workers. The primary thread passes information to a different script which (asynchronously) processes it on a separate thread. The primary thread continues to run and runs a callback occasion when the employee has accomplished its work.

Word that JavaScript makes use of its structured clone algorithm to serialize information right into a string when it’s handed to and from a employee. It will possibly embrace native varieties similar to strings, numbers, Booleans, arrays, and objects — however not capabilities. You received’t be capable of move complicated objects — similar to database connections — since most could have strategies that may’t be cloned. Nonetheless, you can:

  • Asynchronously learn database information in the principle thread and move the ensuing information to the employee.
  • Create one other connection object within the employee. It will have a start-up price, however could also be sensible in case your perform requires additional database queries as a part of the calculation.

The Node.js employee thread API is conceptually much like the Web Workers API within the browser, however there are syntactical variations. Deno and Bun help each the browser and Node.js APIs.

Employee thread demonstration

The next demonstration reveals a Node.js course of which writes the present time to the console each second: Open Node.js demonstration in a new browser tab.

A protracted-running cube throwing calculation then launches on the principle thread. The loop completes 100 million iterations, which stops the time being output:

  timer course of 12:33:18 PM
  timer course of 12:33:19 PM
  timer course of 12:33:20 PM
│ (index) │  Values  │
│    22776134  │
│    35556674  │
│    48335819  │
│    511110893 │
│    613887045 │
│    716669114 │
│    813885068 │
│    911112704 │
│   108332503  │
│   115556106  │
│   122777940  │
processing time: 2961ms

timer course of 12:33:24 PM

As soon as full, the identical calculation launches on a employee thread. The clock continues to run whereas cube processing happens:

  timer course of 12:33:27 PM
  timer course of 12:33:28 PM
  timer course of 12:33:29 PM
│ (index) │  Values  │
│    22778246  │
│    35556129  │
│    48335780  │
│    511114930 │
│    613889458 │
│    716659456 │
│    813889139 │
│    911111219 │
│   108331738  │
│   115556788  │
│   122777117  │
processing time: 2643ms

  timer course of 12:33:30 PM

The employee course of is a little bit quicker than the principle thread as a result of it could actually focus on one activity.

Find out how to use employee threads

A cube.js file within the demonstration challenge defines a dice-throwing perform. It’s handed the variety of runs (throws), the variety of cube, and the variety of sides on every die. On every throw, the perform calculates the cube sum and increments the variety of occasions it’s noticed within the stat array. The perform returns the array when all throws are full:

export perform diceRun(runs = 1, cube = 2, sides = 6) {
  const stat = [];

  whereas (runs > 0) {
    let sum = 0;

    for (let d = cube; d > 0; d--) {
      sum += Math.ground(Math.random() * sides) + 1;
    stat[sum] = (stat[sum] || 0) + 1;

  return stat;

The primary index.js script begins a timer course of which outputs the present date and time each second:

const intlTime = new Intl.DateTimeFormat([], { timeStyle: "medium" });

timer = setInterval(() => {
  console.log(`  timer course of ${ intlTime.format(new Date()) }`);
}, 1000);

When the fundamental thread executes diceRun() immediately, the timer stops as a result of nothing else can run whereas the calculation happens:

import { diceRun } from "./cube.js";

  throws = 100_000_000,
  cube = 2,
  sides = 6;

const stat = diceRun(throws, cube, sides);

To run the calculation in one other thread, the code defines a brand new Worker object with the filename of the employee script. It passes a workerData variable — an object with the properties throws, cube, and sides:

const employee = new Employee("./src/employee.js", {
  workerData: { throws, cube, sides }

This begins the employee script which executes diceRun() with the parameters handed in workerData:

import { workerData, parentPort } from "node:worker_threads";
import { diceRun } from "./cube.js";

const stat = diceRun(workerData.throws, workerData.cube, workerData.sides);


The parentPort.postMessage(stat); name passes the outcome again to the principle thread. This raises a "message" occasion in index.js, which receives the outcome and shows it within the console:

employee.on("message", outcome => {

You may outline handlers for different employee occasions:

  • The primary script can use employee.postMessage(information) to ship arbitrary information to the employee at any level. It triggers a "message" occasion within the employee script:
    parentPort.on("message", information => {
      console.log("from fundamental:", information);
  • "messageerror" triggers in the principle thread when the employee receives information it could actually’t deserialize.
  • "on-line" triggers in the principle thread when the employee thread begins to execute.
  • "error" triggers in the principle thread when a JavaScript error happens within the employee thread. You possibly can use this to terminate the employee. For instance:
    employee.on("error", e => {
  • "exit" triggers in the principle thread when the employee terminates. This could possibly be used for cleansing up, logging, efficiency monitoring, and so forth:
    employee.on("exit", code => {
      console.log("employee full");

Inline employee threads

A single script file can comprise each fundamental and employee code. Your script ought to examine whether or not it’s operating on the principle thread utilizing isMainThread, then name itself as a employee utilizing import.meta.url because the file reference in an ES module (or __filename in CommonJS):

import { Employee, isMainThread, workerData, parentPort } from "node:worker_threads";

if (isMainThread) {

  const employee = new Employee(import.meta.url, {
    workerData: { throws, cube, sides }

  employee.on("message", msg => {});
  employee.on("exit", code => {});

else {

  const stat = diceRun(workerData.throws, workerData.cube, workerData.sides);


Whether or not or not that is sensible is one other matter. I like to recommend you break up fundamental and employee scripts except they’re utilizing an identical modules.

Thread information sharing

You may share information between threads utilizing a SharedArrayBuffer object representing fixed-length uncooked binary information. The next fundamental thread defines 100 numeric components from 0 to 99, which it sends to a employee:

import { Employee } from "node:worker_threads";

  buffer = new SharedArrayBuffer(100 * Int32Array.BYTES_PER_ELEMENT),
  worth = new Int32Array(buffer);

worth.forEach((v,i) => worth[i] = i);

const employee = new Employee("./employee.js");

employee.postMessage({ worth });

The employee can obtain the worth object:

import { parentPort } from 'node:worker_threads';

parentPort.on("message", worth => {
  worth[0] = 100;

At this level, both the principle or employee threads can change components within the worth array and it’s modified in each. It ends in effectivity features as a result of there’s no information serialization, however:

  • you possibly can solely share integers
  • it could be essential to ship messages to point information has modified
  • there’s a threat two threads may change the identical worth on the identical time and lose synchronization

Few apps would require complicated information sharing, but it surely could possibly be a viable possibility in high-performance apps similar to video games.

Node.js Baby Processes

Child processes launch one other utility (not essentially a JavaScript one), move information, and obtain a outcome usually through a callback. They function in an identical solution to staff, however they’re typically much less environment friendly and extra process-intensive, as a result of they’re depending on processes exterior Node.js. There might also be OS variations and incompatibilities.

Node.js has three basic little one course of varieties with synchronous and asynchronous variations:

  • spawn: spawns a brand new course of
  • exec: spawns a shell and runs a command inside it
  • fork: spawns a brand new Node.js course of

The next perform makes use of spawn to run a command asynchronously by passing the command, an arguments array, and a timeout. The promise resolves or rejects with an object containing the properties full (true or false), a code (typically 0 for achievement), and a outcome string:

import { spawn } from 'node:child_process';

perform execute(cmd, args = [], timeout = 600000) {

  return new Promise((resolve, reject) => {

    strive {

        exec = spawn(cmd, args, {

      let ret = '';

      exec.stdout.on('information', information => {
        ret += 'n' + information;

      exec.stderr.on('information', information => {
        ret += 'n' + information;

      exec.on('shut', code => {

          full: !code,
          outcome: ret.trim()


    catch(err) {

        full: false,
        code: err.code,
        outcome: err.message




You should utilize it to run an OS command, similar to itemizing the contents of the working listing as a string on macOS or Linux:

const ls = await execute('ls', ['-la'], 1000);

Node.js Clustering

Node.js clusters mean you can fork quite a few an identical processes to deal with hundreds extra effectively. The preliminary major course of can fork itself — maybe as soon as for every CPU returned by os.cpus(). It will possibly additionally deal with restarts when an occasion fails and dealer communication messages between forked processes.

The cluster library presents properties and strategies together with:

  • .isPrimary or .isMaster: returns true for the principle major course of
  • .fork(): spawns a baby employee course of
  • .isWorker: returns true for employee processes

The instance under begins an online server employee course of for every CPU/core on the system. A 4-core machine will spawn 4 situations of the net server, so it could actually deal with as much as 4 occasions the load. It additionally restarts any course of that fails, so the appliance must be extra sturdy:

import cluster from 'node:cluster';
import course of from 'node:course of';
import { cpus } from 'node:os';
import http from 'node:http';

const cpus = cpus().size;

if (cluster.isPrimary) {

  console.log(`Began major course of: ${ course }`);

  for (let i = 0; i < cpus; i++) {

  cluster.on('exit', (employee, code, sign) => {
    console.log(`employee ${ employee.course } failed`);

else {

  http.createServer((req, res) => {



  console.log(`Began employee course of:  ${ course }`);


All processes share port 8080 and any can deal with an incoming HTTP request. The log when operating the purposes reveals one thing like this:

$ node app.js
Began major course of: 1001
Began employee course of:  1002
Began employee course of:  1003
Began employee course of:  1004
Began employee course of:  1005

...and so forth...

employee 1002 failed
Began employee course of:  1006

Few builders try clustering. The instance above is straightforward and works nicely, however code can develop into more and more complicated as you try to deal with failures, restarts, and messages between forks.

Course of Managers

A Node.js course of supervisor can assist run a number of situations of a single Node.js utility with out having to jot down cluster code. Essentially the most well-known is PM2. The next command begins an occasion of your utility for each CPU/core and restarts any after they fail:

pm2 begin ./app.js -i max

App situations begin within the background, so it’s best for utilizing on a stay server. You may study which processes are operating by coming into pm2 standing:

$ pm2 standing

│ id │ identify │ namespace │ model │ mode    │ pid  │ uptime │
│ 1  │ app  │ default   │ 1.0.0   │ cluster │ 1001 │ 4D     │
│ 2  │ app  │ default   │ 1.0.0   │ cluster │ 1002 │ 4D     │

PM2 may run non-Node.js purposes written in Deno, Bun, Python, and so forth.

Container Orchestration

Clusters and course of managers bind an utility to a selected system. In case your server or an OS dependency fails, your utility fails whatever the variety of operating situations.

Containers are an identical idea to digital machines however, fairly than emulating {hardware}, they emulate an working system. A container is a light-weight wrapper round a single utility with all crucial OS, library, and executable recordsdata. A single container can comprise an remoted occasion of Node.js and your utility, so it runs on a single system or throughout 1000’s of machines.

Container orchestration is past the scope of this text, so it’s best to take a better take a look at Docker and Kubernetes.


Node.js staff and comparable multithreading strategies enhance utility efficiency and scale back bottlenecks by operating code in parallel. They’ll additionally make purposes extra sturdy by operating harmful capabilities in separate threads and terminating them when processing occasions exceed sure limits.

Staff have an overhead, so some experimentation could also be crucial to make sure they enhance outcomes. It’s possible you’ll not require them for heavy asynchronous I/O duties, and course of/container administration can supply a better solution to scale purposes.