Node.js Worker Threads: CPU-Bound Work Without Blocking APIs

One CPU spike can delay every request

Node.js is excellent at concurrent I/O because it can begin a database or network operation and keep processing other callbacks while it waits. JavaScript application code still runs on the event loop, though. A long image transform, large report calculation, PDF parse, encryption pass, or machine-learning feature extraction can keep that loop busy long enough to turn unrelated requests into slow requests.

The symptom is often confusing: CPU usage rises, request latency grows across otherwise healthy endpoints, and timeouts appear even though the database is fast. The right fix is usually to move the computation, not to add more promise chains around it. First, profile the workload and establish a latency budget. Our Next.js observability guide covers the request IDs, timings, and dashboards that make this evidence visible.

Choose worker threads for CPU-bound, in-process jobs

Use a worker when the result is needed during the request or the task is short enough to run locally under a strict deadline. Examples include document previews, server-side image processing, compression, validation of a large payload, or an algorithmic calculation. Use a queue when a customer can be told the work is processing and it needs durable retry and recovery. The Node.js background-jobs guide explains that durable workflow.

Do not create a new worker for every incoming request at high traffic. Startup cost, memory, and contention eventually erase the benefit. A small fixed pool gives the application an honest capacity limit and creates a useful place to apply backpressure.

Build a bounded pool with timeouts and backpressure

A production pool has a maximum number of workers, a bounded waiting queue, a per-job deadline, and a restart policy. Start with a conservative worker count based on allocated CPU—not simply every host core—and load-test the real mix of API traffic. More parallel work can increase context switching and push memory pressure into an outage.

// main process: submit only bounded, serializable jobs
import { Worker } from "node:worker_threads";

function runHashJob(payload) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(new URL("./hash-worker.js", import.meta.url), {
      workerData: payload,
    });
    const timer = setTimeout(() => worker.terminate(), 5_000);

    worker.once("message", (result) => { clearTimeout(timer); resolve(result); });
    worker.once("error", (error) => { clearTimeout(timer); reject(error); });
    worker.once("exit", (code) => {
      if (code !== 0) reject(new Error(`worker stopped with code ${code}`));
    });
  });
}

The example demonstrates lifecycle ownership, not a complete pool. In a pool, return a healthy worker to the idle set after each job, replace a crashed worker, and reject or defer work when the queue is full. A full queue is a capacity signal: respond with a clear retryable status, reduce input size, or hand the task to durable background processing. Never allow an unbounded in-memory queue to become hidden load shedding.

Keep messages small, explicit, and safe to transfer

Workers do not share normal JavaScript memory. They exchange values through structured cloning, transferables, or deliberately shared memory. Design each job as a small contract: a version, an ID, validated input, a cancellation/deadline value, and a result shape. Avoid sending a request object, database client, socket, or mutable application singleton across the boundary.

• Validate job input before it enters the pool, then validate output before it leaves.
• Transfer an ArrayBuffer only when ownership can move; a transferred buffer is no longer usable by its sender.
• Use shared memory only when profiling shows cloning is a real bottleneck and the synchronization design is proven.
• Give jobs stable IDs so logs, metrics, and support incidents can connect a request to worker activity.

A worker can fail after producing a side effect or after its caller times out. If retried work writes to another system, make that downstream operation idempotent. Pair the pool with the durable request ownership described in our Node.js idempotency keys guide; cancellation should not accidentally create duplicate business actions.

Measure saturation before users feel it

Track active workers, idle workers, queue depth, queue wait time, job duration, timeout rate, restart count, memory per worker, and event-loop lag in the main process. Queue wait is particularly valuable: a job can be fast once it runs yet still miss a user-facing deadline because it waited behind too much work. Add job type and release version as low-cardinality dimensions, not raw customer data.

Guard the worker boundary with the same discipline as any other dependency: deadlines, input limits, error classification, and controlled fallback. If a nonessential preview job is overloaded, return a pending state rather than consuming capacity needed for checkout or authentication. For remote dependencies that accompany a CPU job, combine this with the bounded failure behavior in our Node.js circuit-breakers guide.

Finally, rehearse failure. Kill a busy worker, submit malformed input, exceed the queue limit, and deploy while jobs are in flight. Decide which jobs can be abandoned, which must be retried durably, and how the caller learns the outcome. That clarity matters more than the worker API itself.

Node.js worker-thread production checklist