Offload CPU-intensive computation
A server must perform expensive calculations without blocking its event loop.
Node.js · Module
node:worker_threads
node:worker_threads runs JavaScript in parallel in independent threads, making it suitable for CPU-intensive work. Workers communicate through message ports and can transfer or share memory buffers.
- Since
- v10.5.0
How it works
The node:worker_threads module provides independent JavaScript execution threads for parallel work. A Worker communicates with its parent through message ports, while ArrayBuffer objects can be transferred and SharedArrayBuffer objects can be shared.
Syntax
new Worker(filename[, options])Parameters
| Name | Type | Description |
|---|---|---|
filename | string | URL | Worker entry-point filename; the current documentation describes it as a path or URL identifying the worker's main script. |
options | object | Optional Worker configuration, including execution and resource settings. |
Returns
new Worker() returns a Worker instance representing the newly created execution thread.
Key points
- Import node:worker_threads when parallel JavaScript execution is required.
- Each Worker provides a separate JavaScript execution context.
- Use workers to move expensive computation off the main event-loop thread.
- Prefer built-in asynchronous I/O APIs for I/O-bound tasks.
- Data can cross worker boundaries by transferring ArrayBuffer values or sharing SharedArrayBuffer values.
- MessageChannel supplies an asynchronous bidirectional communication path.
Common mistakes
- Use workers for CPU-heavy JavaScript rather than ordinary asynchronous I/O.
- Worker threads are not isolated from one another in the same way as child processes; use transfer or shared buffers deliberately.
- Worker availability of APIs does not mean the worker shares the parent thread's JavaScript state.
Example: Exchange a message with a worker
import { Worker, isMainThread, parentPort } from 'node:worker_threads';
if (isMainThread) {
const worker = new Worker(new URL(import.meta.url));
worker.once('message', (result) => console.log(result));
worker.postMessage(21);
} else {
parentPort.once('message', (value) => parentPort.postMessage(value * 2));
}The main thread starts a worker from the same module, sends it a value, and prints the worker's response.
When to use it
Build worker communication channels
Several worker threads need asynchronous bidirectional messaging.
Transfer or share buffers
Large binary data must cross thread boundaries efficiently.
Run parallel Node.js code
A worker needs access to standard Node.js functionality while running independently.
Interview questions
QWhen should worker_threads be used instead of asynchronous I/O?
The module creates independent JavaScript execution threads, primarily for CPU-intensive operations. It is less useful for I/O because Node's asynchronous I/O is more efficient for that workload.
Follow-up: How can workers exchange data? Through message ports, transferring ArrayBuffer instances, or sharing SharedArrayBuffer instances.
QWhat is a Worker and how does it communicate?
A Worker is an independent JavaScript execution thread. The parent and worker communicate with postMessage-style message events through the worker's communication port.
Follow-up: What object represents a two-way message channel? MessageChannel creates two connected MessagePort instances.
QHow does worker_threads support shared memory?
ArrayBuffer instances can be transferred between threads, while SharedArrayBuffer instances can be shared. This permits data exchange without treating the worker like a child process.
Follow-up: What should be considered when sharing memory? Synchronization and coordination are required because multiple threads can access shared data.
Related
WorkerMessageChannelMessagePortparentPortisMainThreadisInternalThreadthreadIdworkerData