node:worker_threads API Reference

Node.js worker_threads module — real OS-threaded workers with structured-clone messaging

Node.js worker_threads module, resolvable via both ESM import and CommonJS require. Backed by a real host bridge: each Worker runs on its own host thread with its own GraalVM context, realm, and event loop. Messages cross threads by structured clone (guest values never cross realms directly).

import { Worker, isMainThread, parentPort, workerData } from "node:worker_threads";

if (isMainThread) {
  const w = new Worker("./worker.js", { workerData: { n: 41 } });
  w.on("message", (m) => console.log("got", m));
} else {
  parentPort.postMessage(workerData.n + 1);
}

Implemented surface

ExportDescription
WorkerConstructor accepting eval, workerData, transferList, and env options; instances expose postMessage, terminate, ref / unref, and the online / message / messageerror / error / exit events.
isMainThreadtrue on the main thread.
threadIdNumeric ID of the current thread.
parentPortThe MessagePort to the parent (in a worker).
workerDataThe value passed via the workerData option.
SHARE_ENVSentinel for sharing the parent environment.
MessageChannel / MessagePort / BroadcastChannelChannel primitives.
getEnvironmentData / setEnvironmentDataCross-worker environment data.
receiveMessageOnPort(port)Synchronously drain a queued message.
markAsUntransferable / isMarkedAsUntransferable / markAsUncloneablePresent as no-ops.
resourceLimitsThe worker’s resource-limits object.

Not implemented

The following throw ERR_METHOD_NOT_IMPLEMENTED when called: getHeapSnapshot, postMessageToThread, moveMessagePortToContext, and worker.getHeapSnapshot() / worker.getHeapStatistics().

See also