Node.js worker_threads: SharedArrayBuffer and CPU Offloading
Each worker has its own isolate, event loop, and module cache. postMessage copies unless you transfer, and Atomics.wait on the main thread blocks the whole server.

Quick Summary
worker_threads runs JavaScript in parallel inside one process. Each Worker has its own V8 isolate, its own event loop, and its own module cache; memory is shared only if you use a SharedArrayBuffer. That makes it the tool for CPU-bound work — hashing, image resize, JSON parsing of large payloads, report generation — that would otherwise block the main event loop.
Communication is postMessage: values are copied by structured clone, or transferred when an ArrayBuffer or MessagePort is listed in the transfer list, which moves ownership without copying.
The cost is startup. A new Worker re-initialises V8 and re-parses its module graph, tens of milliseconds on a laptop and more on a small container. Spawning one per request is slower than doing the work inline; a pool with a fixed size is the pattern that pays off.
Basic Syntax and Core Signatures
// main.js
import { Worker, isMainThread, parentPort, workerData, MessageChannel, SHARE_ENV } from 'node:worker_threads';
const worker = new Worker(new URL('./worker.js', import.meta.url), {
workerData: { imagePath: 'a.png' },
transferList: [],
env: SHARE_ENV, // share process.env instead of copying
execArgv: [], // do not inherit --inspect etc.
resourceLimits: { maxOldGenerationSizeMb: 256, stackSizeMb: 4 },
name: 'resizer',
});
worker.postMessage({ type: 'resize', width: 512 });
worker.on('message', (msg) => console.log('result', msg));
worker.on('messageerror', (err) => console.error('deserialise failed', err));
worker.on('error', (err) => console.error('worker crashed', err));
worker.on('exit', (code) => console.log('exit', code));
await worker.terminate(); // resolves with the exit code// worker.js
import { parentPort, workerData, threadId } from 'node:worker_threads';
parentPort.postMessage({ threadId, started: Date.now(), input: workerData });
parentPort.on('message', async ({ type, width }) => {
const out = await resize(width);
parentPort.postMessage({ type: 'done', out }, [out.buffer]); // transfer, no copy
});// Shared memory instead of messaging
const sab = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 4);
const counter = new Int32Array(sab);
worker.postMessage({ sab });
// worker side:
Atomics.add(counter, 0, 1);
Atomics.notify(counter, 0);
// main side (waiting blocks this thread):
Atomics.wait(counter, 0, 0, 1000); // value, expected, timeoutKey Comparison Table
| Mechanism | Isolation | Shared state | Startup cost | Use for |
|---|---|---|---|---|
worker_threads | Separate isolate, same process | SharedArrayBuffer, transferred buffers | Tens of ms | CPU-bound work, in-process parallelism |
child_process.fork | Separate process | IPC messages only | Higher, full Node boot | Isolation, crash containment |
cluster | Separate processes | Nothing, shared listening port | Higher | Scaling an HTTP server across cores |
postMessage copy | — | No | Per-message copy | Small structured data |
transferList | — | Ownership moves | Near-zero | Large buffers |
SharedArrayBuffer | — | Yes, with Atomics | Allocation only | Counters, ring buffers, numeric arrays |
| Event | Fires when | Typical handling |
|---|---|---|
message | postMessage arrived | Result handling |
messageerror | Value could not be deserialised | Log, treat as a bug |
error | Uncaught exception in the worker | Mark worker unusable, replace |
exit | Thread ended, code 0 or non-zero | Pool bookkeeping |
online | Worker started executing | Timing measurements |
Practical Edge Cases and Deep Dives
1. A worker per request is slower than no worker
// Wrong under load
app.post('/render', async (req, res) => {
const w = new Worker(new URL('./render.js', import.meta.url));
const out = await once(w, 'message');
res.send(out[0]);
await w.terminate();
});Each request pays isolate startup, module parse, and teardown — often more than the render itself — and a burst of 200 requests spawns 200 isolates, each with its own heap. A fixed pool (four workers on a four-core box, or os.availableParallelism() minus one for the main thread) queues work instead. piscina implements the pool, task queue, and recycling; hand-rolling it is fine for one job type but gets subtle with cancellation and backpressure.
2. Atomics.wait on the main thread blocks everything
const sab = new SharedArrayBuffer(4);
const flag = new Int32Array(sab);
worker.postMessage(sab);
Atomics.wait(flag, 0, 0, 5000); // main thread sleeps: no HTTP, no timers, no GCAtomics.wait blocks the calling thread, and on the main thread that thread runs the event loop. Waiting for a worker this way turns a CPU-bound problem into a total outage. Message-based await once(worker, 'message') is the non-blocking equivalent; Atomics.wait belongs inside the worker, where blocking only pauses that thread.
3. Transferring a pooled ArrayBuffer
const buf = Buffer.from('secret-token'); // from the 8 KiB pool
worker.postMessage({ buf: buf.buffer }, [buf.buffer]); // detaches the whole poolThe transferred ArrayBuffer is the pool slab, not just your bytes, so the worker receives neighbouring allocations too, and your own buffer becomes unusable (byteLength 0). Copy first when transferring: const copy = new Uint8Array(buf); worker.postMessage({ buf: copy }, [copy.buffer]). The same rule applies to any buffer produced by Buffer.allocUnsafe or Buffer.concat on small inputs.
4. Module state is not shared
// main.js
import { registry } from './registry.js'; // one instance
// worker.js
import { registry } from './registry.js'; // a different instance
registry.set('k', 1); // invisible to the main threadEach worker has its own module cache, so singletons, connection pools, and caches are duplicated per thread. A database client created at module scope opens n pools instead of one, which is how a four-worker setup exhausts max_connections. The fix is either to keep I/O in the main thread and send only pure work to workers, or to create the pool inside each worker with a size divided by the thread count.
5. Crashes, resourceLimits, and worker lifetime
const worker = new Worker(url, { resourceLimits: { maxOldGenerationSizeMb: 128 } });
worker.on('error', (err) => {
if (err.code === 'ERR_WORKER_OUT_OF_MEMORY') replace(worker);
});
worker.unref(); // do not keep the process alive for this workerAn uncaught exception inside a worker emits error on the parent; if nothing listens, it crashes the main process. A worker that dies cannot be restarted in place — create a new one and remove the dead entry from the pool. resourceLimits is the only way to cap a worker's heap, and exceeding it terminates the thread with ERR_WORKER_OUT_OF_MEMORY rather than degrading the whole process. A worker keeps the process alive by default, so unref() is required for background workers in a CLI.
6. cluster versus workers for an HTTP server
import cluster from 'node:cluster';
if (cluster.isPrimary) {
for (let i = 0; i < 4; i++) cluster.fork();
} else {
http.createServer(handler).listen(3000);
}cluster starts separate processes that share the listening socket, so each has its own heap and one crashing does not take down the others — at the cost of per-process memory and no shared state at all. worker_threads shares the process, which makes passing buffers cheap and memory smaller, but a fatal error in one thread can still end the process. Modern advice is to run one Node process per container and scale with the container, using worker_threads only for CPU-bound tasks inside it.
Common Node.js Runtime Mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Throughput drops when workers are added | Worker created per task | Fixed-size pool |
| API stops responding under load | Atomics.wait on the main thread | Message-based waiting |
| Worker receives unrelated bytes | Transferred a pooled ArrayBuffer | Copy before transfer |
DataCloneError on postMessage | Value is not structured-cloneable (function, class instance) | Send plain data |
ERR_WORKER_OUT_OF_MEMORY | resourceLimits too low, or a real leak | Raise the limit, fix the leak |
| Process never exits | Active worker | worker.unref() or terminate() |
| Database connections multiplied by four | Module-scope pool per worker | Split the pool, or keep I/O in main |
| Main process crashes on a worker bug | No 'error' listener | Handle 'error', replace the worker |
| Stale config after a change | Each worker parsed the module at startup | Recycle workers on deploy |
Try matching browser tools
All toolsSmall utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Node.js guides
All Node.js guidesNode.js EventEmitter: once, error Events, and Listener Memory Leaks
emit is synchronous, so a throwing listener aborts the rest. An error event with no listener crashes the process, and a listener per request is the classic leak.
Node.js fs/promises: Read, Write, Watch, and Atomic File Operations
writeFile truncates before writing, so a crash leaves half a file. The atomic pattern is temp file, fsync, rename; readFile loads everything, so large files need streams.
Node.js Streams: Readable, Writable, Transform, and pipeline
pipe() forwards data but not errors; pipeline() destroys the chain and rejects. Backpressure is the false return from write(), and _flush that never calls back hangs forever.
Node.js crypto: Hashing, HMAC, AES-GCM, and Random Bytes
Hashing, HMAC, AES-256-GCM and randomness solve different problems. Never reuse a GCM nonce, never hash a password with sha256, and compare secrets with timingSafeEqual.
More in Node.js
All Node.js guidesThe guides filed next to this one in Node.js, in library order.