Is your task actually CPU-bound and blocking the event loop?
Worker threads exist for one problem: JavaScript that keeps the main thread busy long enough to stall every other request on the process. Node runs your JavaScript on a single thread, so a 200 ms synchronous hash blocks everything else for 200 ms, including health checks. I/O is different. Sockets, files and database drivers already hand work to the OS or libuv and return to the event loop while they wait. Moving an awaited query into a thread adds overhead and does not make it faster.
| Task | Blocks the main thread? | Offloading to a worker helps? |
|---|---|---|
| Database queries, HTTP calls | No | No |
crypto.pbkdf2Sync, zlib.gzipSync |
Yes | Yes, or use the async variant |
| Image or PDF rendering in pure JS | Yes | Yes |
Large JSON.parse/stringify |
Yes | Sometimes; copying the result back can cost nearly as much |
| Regex-heavy parsing of big inputs | Yes | Yes |
Measure before changing anything. monitorEventLoopDelay from perf_hooks records a histogram of how late the loop runs. Read its p99 and max values, not the mean, because a few long stalls are what hurt users. Use a CPU profile to find the function responsible. You can start Node with --cpu-prof or attach the inspector during a load test. Then compare p95/p99 request latency under realistic concurrency. Averages hide blocking because most requests finish quickly while a few queue behind one slow task. If the tail stays flat while loop delay stays low, the bottleneck is elsewhere.
// Run with: node --cpu-prof server.js (writes a .cpuprofile on exit for DevTools)
const http = require('node:http');
const crypto = require('node:crypto');
const { monitorEventLoopDelay } = require('node:perf_hooks');
// Sample event loop delay every 20 ms; values are reported in nanoseconds.
const loopDelay = monitorEventLoopDelay({ resolution: 20 });
loopDelay.enable();
const toMs = (ns) => (ns / 1e6).toFixed(1);
// Log tail delay, not just the mean: a few long stalls are what users feel.
setInterval(() => {
console.log(
`loop delay ms mean=${toMs(loopDelay.mean)}` +
` p99=${toMs(loopDelay.percentile(99))} max=${toMs(loopDelay.max)}`
);
loopDelay.reset(); // report each window separately
}, 5000).unref();
http.createServer((req, res) => {
if (req.url === '/hash') {
// Synchronous CPU work: blocks every other request until it finishes.
const key = crypto.pbkdf2Sync('example-password', 'example-salt', 300000, 64, 'sha512');
res.end(key.toString('hex'));
return;
}
// Cheap route: its p99 latency rises whenever /hash is running.
res.end('ok');
}).listen(3000);
// Under load, a high p99/max here plus a pbkdf2Sync hotspot in the CPU profile
// means the work is CPU-bound and a worker (or async pbkdf2) will help.
A minimal server that logs event loop delay p99 and max with monitorEventLoopDelay while a synchronous pbkdf2Sync route blocks the loop, run under --cpu-prof to locate the hot function.
Who should use worker threads?
Worker threads are aimed at engineers who run Node.js services that are mostly I/O-bound but have a few endpoints or jobs that do heavy computation. The measurements above should show that such a code path exists before you reach for them. Typical cases:
- API teams with one or two CPU-heavy routes. Examples are password hashing, report generation, image resizing or PDF rendering in pure JavaScript, compression, and parsing large documents. The rest of the service is database and HTTP calls that are fine on the main thread.
- Teams that want to keep the work in-process. If the CPU-bound task needs the request's result synchronously and is not big enough to justify a separate service or job queue, a worker pool keeps it in the same codebase, deployment and language.
- Authors of CLI tools, build scripts and batch jobs. These process many files or records and can spread pure-JavaScript computation across cores without spawning separate processes.
- Library authors who ship CPU-heavy functionality and want to offer a non-blocking API to Node.js callers.
If your profiles show the event loop is not blocked, or the expensive work already has an async variant that runs on the libuv threadpool (such as crypto.pbkdf2 or the async zlib functions), you probably do not need worker threads. The last section of this article covers that in more detail.
How does it work? Inside Node.js worker threads
Each worker is a separate Node.js instance inside the same process. It gets its own V8 isolate, heap and event loop, so JavaScript running in a worker cannot touch the main thread's objects. That isolation is why a tight loop in a worker leaves request handling alone, and also why every input and result has to be passed explicitly.
In practice the flow is: the main thread receives a request, posts a small message describing the task to a worker, and keeps serving other requests. The worker runs the computation on its own thread and posts the result back. The main thread receives that result as a message event on its event loop and finishes the response.
HTTP requests
│
┌─────▼───────┐ postMessage ┌────────────┐ ┌─────────────────────┐
│ Main thread │──────────────►│ Task queue │────►│ Worker pool │
│ event loop │◄──────────────│ (bounded) │ │ [W1] [W2] [W3] [W4] │
└─────┬───────┘ results └────────────┘ │ own isolate + loop │
│ └──────────┬──────────┘
│ fs, dns.lookup, crypto, zlib │
└───────────────►┌──────────────────┐◄────────────────┘
│ libuv threadpool │ (one per process,
└──────────────────┘ shared by all threads)
postMessage copies data using the structured clone algorithm. Cloning runs synchronously on both ends. Serializing a large object graph therefore blocks the main loop for the duration of the copy, which is the stall you were trying to avoid. Transferable objects such as ArrayBuffer avoid the copy by moving ownership. After the transfer, the sender's buffer is detached and unusable. SharedArrayBuffer goes further: both threads see the same memory, and you coordinate access with Atomics operations such as Atomics.wait and Atomics.notify. That gives you real shared state, along with the race conditions that come with it.
Every task pays for messaging, cloning and scheduling. A job that takes a fraction of a millisecond inline can take longer once it goes through a worker. Offloading only pays off when the compute time clearly exceeds that round-trip overhead.
// worker-demo.js (run with: node worker-demo.js)
const { Worker, isMainThread, parentPort, workerData } = require('node:worker_threads');
if (isMainThread) {
// SharedArrayBuffer: shared with the worker, not copied. Both threads see these 4 bytes.
const shared = new SharedArrayBuffer(4);
const flag = new Int32Array(shared);
const worker = new Worker(__filename, { workerData: { shared } });
// Transfer instead of clone: the transfer list moves ownership of the 8 MB buffer.
const input = new ArrayBuffer(8 * 1024 * 1024);
worker.postMessage({ input }, [input]);
// The sender's buffer is now detached and unusable.
console.log('main byteLength after transfer:', input.byteLength); // 0
worker.on('message', ({ sum }) => {
console.log('sum from worker:', sum);
console.log('shared flag:', Atomics.load(flag, 0)); // 1, written by the worker
worker.terminate();
});
} else {
const flag = new Int32Array(workerData.shared);
parentPort.on('message', ({ input }) => {
// CPU-bound loop runs on the worker's own event loop, so the main thread stays free.
const bytes = new Uint8Array(input);
bytes.fill(1);
let sum = 0;
for (let i = 0; i < bytes.length; i++) sum += bytes[i];
// Publish state through shared memory and wake any thread blocked in Atomics.wait.
Atomics.store(flag, 0, 1);
Atomics.notify(flag, 0);
// The result is small, so cloning it is cheap.
parentPort.postMessage({ sum });
});
}
A single-file worker that receives a transferred ArrayBuffer, which detaches it on the main thread, and signals completion through a SharedArrayBuffer using Atomics.store and Atomics.notify.
Why is spawning a worker per request an anti-pattern?
Creating a Worker per request makes that overhead much worse. Each new worker starts an OS thread, creates a fresh V8 isolate with its own heap, and boots a separate Node.js environment with its own event loop. It then loads and compiles your worker script and everything that script imports. None of this is shared with the main thread or with other workers. A worker that needs a hashing library or a template engine pays for loading it again every time. The JIT also starts cold each time, so hot code never gets optimized across requests.
Memory is a second problem. Every live worker has its own heap and baseline runtime footprint. If you spawn workers on demand, concurrency is set by incoming traffic instead of by you. A burst of requests becomes a burst of threads competing for the same cores. That raises memory pressure and context switching, and it can trigger out-of-memory failures exactly when load peaks.
The fix is to pay startup costs once and keep a fixed number of workers. A minimal pool needs four parts:
- A fixed set of long-lived workers, created at boot. Each one listens for task messages and posts results back.
- An idle list that tracks which workers are free.
- A FIFO queue of pending tasks. Each task carries its input plus the resolve and reject callbacks of the promise returned to the caller.
- A dispatch step that runs on every submit and on every completed result. It pairs the next queued task with an idle worker.
Because the number of workers is capped, excess work waits in the queue instead of creating new threads.
// pool.js: one file acts as both main thread and worker script (CommonJS).
const { Worker, isMainThread, parentPort } = require('node:worker_threads');
const os = require('node:os');
if (!isMainThread) {
// Worker side: modules load and JIT warms up once, then serve many tasks.
const crypto = require('node:crypto');
parentPort.on('message', ({ password, salt }) => {
const hash = crypto.pbkdf2Sync(password, salt, 100000, 64, 'sha512');
parentPort.postMessage(hash.toString('hex'));
});
} else {
class WorkerPool {
constructor(size) {
this.idle = []; // workers free to take a task
this.queue = []; // FIFO of { data, resolve, reject }
this.active = new Map(); // worker -> task it is running
for (let i = 0; i < size; i++) {
const w = new Worker(__filename); // startup cost paid once, at boot
w.on('message', (result) => this.finish(w, null, result));
w.on('error', (err) => this.finish(w, err)); // a production pool would also replace the dead worker
this.idle.push(w);
}
}
run(data) {
return new Promise((resolve, reject) => {
this.queue.push({ data, resolve, reject }); // excess work waits here, no new threads
this.dispatch();
});
}
dispatch() { // pair queued tasks with idle workers
while (this.idle.length && this.queue.length) {
const w = this.idle.pop(), task = this.queue.shift();
this.active.set(w, task);
w.postMessage(task.data);
}
}
finish(w, err, result) {
const task = this.active.get(w);
this.active.delete(w);
if (err) task?.reject(err); else { task.resolve(result); this.idle.push(w); } // errored workers have exited; do not reuse
this.dispatch();
}
}
const pool = new WorkerPool(Math.max(1, os.cpus().length - 1)); // concurrency set by you, not by traffic
pool.run({ password: 'example-password', salt: 'example-salt' }).then(console.log);
}
A minimal hand-rolled pool that creates a fixed set of long-lived workers at boot, tracks idle workers, queues tasks FIFO with their promise callbacks, and dispatches on every submit and every completed result.
How do you implement a bounded pool with piscina?
Piscina packages that scheduling loop as a library. You create one pool at process startup, point it at a worker module that exports a single function, and call run() with a task. run() returns a promise that settles when a worker finishes. The core options are:
minThreadskeeps workers warm, so the first requests after a quiet period don't pay startup cost.maxThreadsis the hard ceiling that makes the pool bounded.idleTimeoutlets extra workers exit after load drops, which returns memory.maxQueuecaps how many tasks can wait. Without it the queue becomes the unbounded part of the system.
For cancellation, pass an AbortSignal in the options to run(). If the client disconnects or your request deadline expires, abort the signal. A task that is still queued is dropped. A task that is already running ends when piscina terminates its worker, and the pool replaces that worker. Either way, cancelled work stops consuming capacity.
Keep the handler thin
The route handler should validate input, take only the fields the computation needs, call pool.run(), and map the result or error to a response. It should not hand over the raw request body or a large object graph. Arguments are copied with the structured clone algorithm, and that copying happens synchronously on the main thread. Cloning a multi-megabyte payload blocks the event loop, which is the problem the pool is meant to solve. Send IDs, small parameters, or ArrayBuffers listed in a transfer list so they move without being copied.
Why not write your own
A homemade pool tends to start at about fifty lines. It grows to cover crashed workers, queue limits, abort handling across the queued and running states, and utilization metrics. Each of those is a place where subtle bugs show up under load. Using a maintained pool hands that edge-case work to code that many production systems already run.
const path = require('node:path');
const express = require('express');
const Piscina = require('piscina');
const MAX_QUEUE = 100;
// One bounded pool per process, created at startup and shared by all requests.
const pool = new Piscina({
filename: path.resolve(__dirname, 'digest-worker.js'), // exports ({ reportId, rounds }) => result
minThreads: 2, // keep two workers warm so requests after a quiet period skip startup
maxThreads: 4, // hard ceiling on concurrent CPU-bound tasks
idleTimeout: 30000, // extra workers exit after 30s idle and return their memory
maxQueue: MAX_QUEUE, // bounded backlog so the queue does not grow without limit
});
const app = express();
app.use(express.json({ limit: '10kb' })); // reject large bodies before they reach the handler
app.post('/reports/:id/digest', async (req, res) => {
const rounds = Number(req.body.rounds);
if (!Number.isInteger(rounds) || rounds < 1 || rounds > 1000) {
return res.status(400).json({ error: 'rounds must be an integer from 1 to 1000' });
}
// Shed load early instead of queueing work we cannot finish in time.
if (pool.queueSize >= MAX_QUEUE) return res.status(503).json({ error: 'busy, retry later' });
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 2000); // request deadline
res.on('close', () => ac.abort()); // client disconnected (harmless after completion)
try {
// Only an ID and a small number are cloned; the worker loads the report data itself.
const digest = await pool.run({ reportId: req.params.id, rounds }, { signal: ac.signal });
res.json({ digest });
} catch (err) {
if (!res.headersSent) res.status(ac.signal.aborted ? 504 : 500).json({ error: 'digest failed' });
} finally {
clearTimeout(timer);
}
});
app.listen(3000);
A single bounded piscina pool configured with minThreads, maxThreads, idleTimeout and maxQueue, used by a thin Express handler that sends only an ID and a small parameter, sheds load when the queue is full, and cancels the task through an AbortSignal on deadline or client disconnect.
How should you size the pool and handle overload?
Start from os.availableParallelism(), or os.cpus().length where it isn't available, and subtract headroom. The main thread still parses requests, serializes responses and moves messages to and from workers. The libuv threadpool still serves file system, DNS and crypto calls. On a dedicated host, cores minus one is a reasonable starting point.
Containers complicate this. A CPU quota enforced through cgroups may not be reflected in what the runtime reports, so a pod limited to two CPUs on a 32-core node can spawn 31 workers. Those threads compete for two CPUs' worth of time, get throttled, and every task slows down. Read the limit from your deployment config or an environment variable and set maxThreads explicitly.
Bound the queue with maxQueue. When it is full, reject immediately with 429 or 503 and a Retry-After header. A fast rejection lets clients and load balancers back off. A long queue only hides overload until requests time out anyway.
Tie each task to the request's lifetime. Pass an AbortSignal that fires on request timeout or client disconnect, so queued tasks are dropped before they start. A synchronous loop that is already running cannot observe the signal. The only way to stop it is to terminate the worker and let the pool replace it.
Illustrative estimate. Assume a 4-core machine, 3 workers, and 50 ms of CPU per task. Capacity is 3 × 20 = 60 tasks/s. At 80 requests/s, the queue grows by 20 tasks each second:
| Elapsed | Queue depth | Added wait per new request |
|---|---|---|
| 1 s | 20 | ~0.33 s |
| 5 s | 100 | ~1.67 s |
| 10 s | 200 | ~3.33 s |
Latency keeps rising for as long as demand exceeds capacity. That is why the queue needs a cap.
Error handling, worker lifecycle and observability
An uncaught exception inside a worker does not crash the main process. The Worker object in the parent emits 'error' with the thrown value, and the thread then stops and emits 'exit' with its exit code. If you manage raw workers, listen for both. Use 'error' to fail whichever request was waiting on that worker, and use 'exit' to start a replacement, with a backoff so that a task that always crashes cannot cause a respawn loop. With piscina, the task's promise rejects and the pool replaces the dead thread, so the error handling lives in your request handler.
A crash is easier to deal with than a task that keeps allocating memory. Set resourceLimits (for example maxOldGenerationSizeMb) so that V8 terminates the worker's isolate when it exceeds its heap budget. Only that worker dies, and the caller gets an out-of-memory error. Without the limit, the worker's allocations count against the memory of the whole process, and the container's OOM killer can take down every in-flight request.
Request context does not carry over into a worker. Each worker has its own AsyncLocalStorage instances, its own module state and its own logger. An error thrown in the worker also loses the stack of the request that dispatched it. To keep context:
- Pass the correlation ID and any other context fields in the task payload.
- Have the worker include the correlation ID in every log line it writes.
- Wrap rejections on the main thread so the error carries both the worker's stack and the request's ID.
This adds ongoing cost. Debuggers attach to each thread separately, logs from different threads interleave, and you have to maintain the context passing yourself. Account for that cost when you decide whether to use worker threads.
How can worker threads save engineering time?
Engineers mostly save time by avoiding work they would otherwise have to do, not because worker threads are free to adopt.
- No new service to build and run. The usual alternative for a CPU-heavy endpoint is to split it into a separate service or put it behind a job queue. That means a new deployment, a new API contract, retries, result delivery and another thing to monitor. A worker pool keeps the code in the same repository, the same language, the same deployment and the same test suite. The change is usually confined to moving one function into a worker module and replacing its call with
pool.run(). - No rewrite in native code. Before porting a hot loop to a native addon or WebAssembly, moving it off the main thread is often enough to stop it from blocking other requests. You can keep the existing JavaScript implementation, along with its tests.
- Fewer hard-to-diagnose latency incidents. Event-loop stalls show up as unrelated slow requests, failed health checks and timeouts on endpoints that do no heavy work. These are slow to trace back to their cause. Once the CPU-bound path runs in a bounded pool, and loop delay is tracked with
monitorEventLoopDelay, a stall shows up as a queue-depth or loop-delay metric instead of a mystery. - Less pool code to own. Using a maintained pool such as piscina instead of a homemade one removes the code for crash recovery, queue limits and cancellation, which is the code most likely to break under load.
- Measuring first avoids wasted effort. The profiling step at the start of this article tells you whether offloading will help. Skipping it is how teams end up moving I/O-bound code into workers and gaining nothing.
The savings depend on how much of the alternative you would otherwise build. Treat any estimate as illustrative and base it on your own assumed inputs: compare the time to move one function behind a pool and add the context passing described above with the time to stand up, deploy and operate a separate service for the same work.
When should you avoid worker threads, and what are the alternatives?
Worker threads are the wrong tool in four common situations:
- I/O-bound code. Database calls, HTTP requests and file reads already run off the main thread through libuv and the OS. Moving them into a worker adds a hop without freeing any CPU.
- Tiny tasks. Arguments and results are structured-cloned across the thread boundary. If a task finishes in microseconds, cloning and message passing can cost more than the work itself.
- CPU demand above available cores. A pool spreads work across cores but does not add any. When sustained demand exceeds capacity, the queue grows and latency climbs.
- Memory-constrained containers. Each worker runs its own V8 isolate and heap. A pool sized for the core count can push a container past its memory limit and get it killed.
| Alternative | Fits when | Main cost |
|---|---|---|
| Separate service or job queue | Work can be asynchronous or needs independent scaling | Extra infrastructure, retries, result delivery |
| Native addon or WebAssembly | A hot loop dominates and a faster implementation exists | Build toolchain, harder debugging |
Child processes or cluster |
You need crash or memory isolation | Higher memory use, IPC serialization |
| Horizontal scaling | Load is high but individual tasks are cheap | More instances to run and pay for |
| Algorithmic fix | The work is inefficient, such as quadratic parsing | Engineering time, with no runtime cost afterward |
Every option shifts cost somewhere else. A bounded pool also forces a product decision: when the queue is full, some requests get a 429 or 503. Agree on that rejection policy with product owners before you ship. Leaving it implicit just turns overload into timeouts.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to node.js worker threads, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.