karawaci.kode

2026-09-02 · 9 min

Node.js Worker Threads for CPU-Intensive Tasks: A Production Guide for 2026

Your Node.js event loop handles 10,000 concurrent requests with ease — until one request triggers a 200ms JSON transformation across a 50MB payload and the entire server stalls. This is where most backend engineers discover that Node.js’s single-threaded model is not a limitation you work around, but a contract you need to understand. Worker threads in Node.js give you real CPU parallelism without abandoning the event loop model that makes Node.js fast for I/O.

This is not a theoretical overview. It is what I actually use in production, with the real failure modes included.

Why the Event Loop Stalls on CPU Work

The event loop is non-blocking for I/O because network and disk operations are handed off to the OS. The OS signals completion, the loop picks it up, your callback runs. Zero blocking.

CPU work is different. There is no OS to hand it off to. Parsing a large CSV, computing a bcrypt hash at cost factor 14, running a naive image resize — all of that runs on the main thread, blocking every other request until it finishes. One 300ms CPU task on a busy API server means every concurrent request waits 300ms for no reason.

The standard advice has long been to use child processes or offload to a queue worker. Both work. But they carry overhead: process startup time, IPC serialization, and separate memory spaces. Node.js worker threads, stable since v12 and mature by v18, are a better fit for in-process CPU parallelism.

The Minimal Worker Thread Pattern

The core API is straightforward. You spawn a Worker, post messages to it, and receive results back.

// main.js
import { Worker } from 'node:worker_threads';
import { fileURLToPath } from 'node:url';
import path from 'node:path';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

function runWorker(workerData) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(
      path.join(__dirname, 'worker.js'),
      { workerData }
    );

    worker.once('message', resolve);
    worker.once('error', reject);
    worker.once('exit', (code) => {
      if (code !== 0) {
        reject(new Error(`Worker exited with code ${code}`));
      }
    });
  });
}

// Usage: non-blocking from the caller's perspective
const result = await runWorker({ csvData: largeBuffer });
console.log(result.rowCount);
// worker.js
import { workerData, parentPort } from 'node:worker_threads';

function parseCSV(data) {
  // CPU-intensive work here — runs in a separate thread
  const lines = data.split('\n');
  const rows = lines.map(line => line.split(','));
  return { rowCount: rows.length, headers: rows[0] };
}

const result = parseCSV(workerData.csvData);
parentPort.postMessage(result);

This works. But spawning a new worker per task is expensive — worker startup can take 30–80ms depending on what you import. For a server handling bursts of CPU tasks, that overhead compounds fast.

Building a Worker Pool

Near BSD Serpong, a logistics client I work with runs batch invoice generation nightly. Each invoice involves PDF layout math across hundreds of line items. The naive approach of one worker per invoice made the batch slower than the single-threaded version because of spawn overhead. A pool fixed it.

// worker-pool.js
import { Worker } from 'node:worker_threads';
import os from 'node:os';

export class WorkerPool {
  #size;
  #workers = [];
  #queue = [];
  #available = [];

  constructor(workerFile, size = os.availableParallelism()) {
    this.#size = size;

    for (let i = 0; i < size; i++) {
      const worker = new Worker(workerFile);
      this.#workers.push(worker);
      this.#available.push(worker);

      worker.on('message', (result) => {
        const { resolve } = worker._currentTask;
        worker._currentTask = null;
        this.#available.push(worker);
        this.#dispatch();
        resolve(result);
      });

      worker.on('error', (err) => {
        const { reject } = worker._currentTask;
        worker._currentTask = null;
        // Replace the crashed worker
        this.#replaceWorker(worker);
        reject(err);
      });
    }
  }

  run(data) {
    return new Promise((resolve, reject) => {
      this.#queue.push({ data, resolve, reject });
      this.#dispatch();
    });
  }

  #dispatch() {
    if (this.#queue.length === 0 || this.#available.length === 0) return;
    const worker = this.#available.pop();
    const task = this.#queue.shift();
    worker._currentTask = task;
    worker.postMessage(task.data);
  }

  #replaceWorker(deadWorker) {
    const idx = this.#workers.indexOf(deadWorker);
    const newWorker = new Worker(deadWorker.resourceLimits?.workerFile ?? '');
    this.#workers[idx] = newWorker;
    this.#available.push(newWorker);
    this.#dispatch();
  }

  async destroy() {
    await Promise.all(this.#workers.map(w => w.terminate()));
  }
}
// app startup — create once, reuse across requests
import { WorkerPool } from './worker-pool.js';

const pool = new WorkerPool(
  new URL('./workers/invoice.js', import.meta.url).pathname
);

// In your request handler
app.post('/invoices/generate', async (req, res) => {
  const result = await pool.run(req.body);
  res.json(result);
});

Pool size defaults to os.availableParallelism(). On a 4-core container, that is 4 workers. Spawning 20 workers on a 4-core machine does not give you 5x throughput — it gives you context switching overhead and memory pressure.

Zero-Copy Data Transfer with Transferables

The moment your worker tasks operate on binary data — image buffers, audio samples, typed arrays — serialization becomes the bottleneck. postMessage with a plain object clones the data. An 8MB ArrayBuffer takes measurable time to clone on every round trip.

Transferable objects skip the copy entirely. Ownership moves from sender to receiver, and the original reference becomes detached.

// In your worker.js (image processing example)
import { workerData, parentPort } from 'node:worker_threads';

// workerData.buffer is an ArrayBuffer transferred with zero copy
const input = new Uint8ClampedArray(workerData.buffer);
const output = processPixels(input); // your CPU-bound operation

// Transfer the result buffer back — no copy
parentPort.postMessage(
  { buffer: output.buffer },
  [output.buffer]  // second arg: list of transferables
);
// Caller side — note the transfer list
const imageBuffer = getImageBuffer(); // ArrayBuffer

worker.postMessage(
  { buffer: imageBuffer },
  [imageBuffer] // transfer, not copy
);

// imageBuffer is now detached here — byteLength === 0
// Do not use it after this point

The gotcha: once transferred, the sender’s reference is invalid. This catches engineers who try to reuse the buffer after posting. The structured clone error you get is not immediately obvious about why. Mark transferred buffers as dead at the call site.

SharedArrayBuffer for High-Frequency Communication

Transferables are one-way. For scenarios where multiple workers read from a shared dataset — a lookup table, a configuration blob, a pre-computed index — SharedArrayBuffer lets all threads access the same memory region without any copying.

// Build a shared lookup table at startup
const LOOKUP_SIZE = 1024 * 1024; // 1MB
const sharedBuffer = new SharedArrayBuffer(LOOKUP_SIZE);
const lookup = new Int32Array(sharedBuffer);

// Populate once on the main thread
populateLookupTable(lookup);

// Pass the shared buffer to all workers at construction time
const worker = new Worker('./worker.js', {
  workerData: { sharedBuffer }  // SharedArrayBuffer passes by reference
});
// worker.js — reads the shared table without any message passing
import { workerData } from 'node:worker_threads';

const lookup = new Int32Array(workerData.sharedBuffer);

// Reads are instant — no serialization, no IPC
function compute(key) {
  return lookup[key % lookup.length];
}

If multiple workers write to shared memory concurrently, use Atomics to avoid data races. Atomics.add, Atomics.compareExchange, Atomics.wait and Atomics.notify give you the primitives. This is territory where a single misunderstood race condition causes bugs that are nearly impossible to reproduce in development. Keep shared write paths narrow and explicit.

Error Handling and Worker Recovery

Workers that throw uncaught exceptions terminate and emit an error event on the parent. Without handling this, an unhandled rejection can crash your entire server process in some configurations.

The pool implementation above replaces dead workers. For standalone workers, the pattern is:

worker.on('error', (err) => {
  logger.error({ err, workerId: worker.threadId }, 'Worker crashed');
  // Decide: replace, alert, or degrade gracefully
  metrics.increment('worker.crash');
});

worker.on('exit', (code) => {
  if (code !== 0) {
    logger.warn({ code }, 'Worker exited with non-zero code');
  }
});

One non-obvious behavior: if a worker exits cleanly (finishes its task and the script ends), it is gone. Workers that need to stay alive for the pool must loop, waiting for messages:

// Persistent worker that stays alive
import { parentPort } from 'node:worker_threads';

parentPort.on('message', async (task) => {
  const result = await processTask(task);
  parentPort.postMessage(result);
  // Does NOT exit — stays alive for the next message
});

What Not to Use Worker Threads For

Worker threads are the right tool for synchronous, CPU-bound operations. They are the wrong tool for I/O-bound work. If your “slow” task is actually awaiting a database query or an HTTP call, adding worker threads does nothing — you are not blocking the event loop, you are waiting on network. Worker threads for async I/O work add spawn overhead without any benefit.

Profile before reaching for threads. A quick console.time around the suspect function, or clinic.js flame for a proper flame graph, tells you whether your bottleneck is CPU or I/O. Most of the time, the answer surprises you.

Production Checklist

Before shipping worker thread code to production, verify:

  • Pool size is set from os.availableParallelism(), not a hardcoded number
  • Worker errors are caught and workers are replaced, not left as silent gaps in the pool
  • Large binary payloads use Transferables, not raw postMessage with objects
  • Workers are created once at startup, not per request
  • SharedArrayBuffer writes are protected by Atomics if more than one thread writes
  • Graceful shutdown calls pool.destroy() to terminate workers cleanly — otherwise the process hangs

The event loop is still the right model for most of what Node.js does. Worker threads are a targeted instrument for the specific case where JavaScript computation is the bottleneck. Used in the right place, they bring genuine parallelism without reaching for a different runtime.

Used in the wrong place, they add complexity for zero gain. Know which one you have before you reach for the API.

Ditulis oleh Reza Pradipta