worker_threads

worker_threads offload CPU-heavy JavaScript to parallel threads without spawning a new OS process - use workerData, message passing, and optionally SharedArrayBuffer for shared state.

Recipe

import { Worker } from 'node:worker_threads';
import { fileURLToPath } from 'node:url';
 
const worker = new Worker(fileURLToPath(new URL('./hash-worker.js', import.meta.url)), {
  workerData: { input: 'payload' },
});
 
worker.on('message', (result) => console.log(result));

When to reach for this:

• bcrypt/scrypt rounds, image resize, PDF generation in JS
• Large JSON transform or CSV parse blocking event loop
• Parallel map over CPU work items with fixed pool size
• Crypto operations not delegating to crypto thread pool sufficiently

Working Example

// main.ts
import { Worker } from 'node:worker_threads';
import { cpus } from 'node:os';
import { fileURLToPath } from 'node:url';
 
const poolSize = Math.min(4, cpus().length);
const workers: Worker[] = [];
const queue: Array<{ data: number[]; resolve: (v: number) => void }> = [];
 
for (let i = 0; i < poolSize; i++) {
  const w = new Worker(fileURLToPath(new URL('./sum-worker.js', import.meta.url)));
  w.on('message', (sum: number) => {
    const job = queue.shift();
    job?.resolve(sum);
    w.postMessage(job?.data ?? []);
  });
  workers.push(w);
}
 
export function sumInWorker(nums: number[]): Promise<number> {
  return new Promise((resolve) => {
    queue.push({ data: nums, resolve });
    const idle = workers.find((w) => !w.threadId) ?? workers[0];
    idle.postMessage(nums);
  });
}

// sum-worker.js
import { parentPort, workerData } from 'node:worker_threads';
 
parentPort?.on('message', (nums: number[]) => {
  const sum = nums.reduce((a, b) => a + b, 0);
  parentPort?.postMessage(sum);
});
 
if (workerData) {
  parentPort?.postMessage('ready');
}

What this demonstrates:

• Pool size capped - do not spawn unbounded workers per request
• postMessage uses structured clone algorithm - not for huge graphs every tick
• Separate worker entry file - no eval: true in production
• Queue pairs jobs with workers - production pools use mature libraries or robust scheduling

Deep Dive

How It Works

• Each Worker is a thread with isolated JS heap except shared memory explicitly shared.
• workerData cloned once at construction.
• parentPort.postMessage async between threads - serialized copies.
• SharedArrayBuffer + Atomics for lock-free counters - advanced, careful with races.

worker_threads vs child_process

TypeScript Notes

import { isMainThread, parentPort, workerData } from 'node:worker_threads';
 
if (!isMainThread) {
  const { job } = workerData as { job: string };
  parentPort?.postMessage({ ok: true, job });
}

Gotchas

• Spawning worker per HTTP request - thread explosion. Fix: fixed pool reused across requests.
• Posting huge objects frequently - clone cost dominates. Fix: SharedArrayBuffer or transfer ArrayBuffers with transfer list.
• Shared mutable state without Atomics - data races. Fix: message passing default; SAB only when measured need.
• Native addons not thread-safe - undefined behavior. Fix: run addon in main thread or documented thread-safe mode.
• Unhandled errors in worker - emit error event - attach handler or worker.on('error') crashes supervision.

Alternatives

FAQs

Related

• Detecting Event-Loop Blockage - when to offload
• child_process - OS processes
• Processes Basics - decision overview
• Event Loop Best Practices - main thread rules

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.