Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js workerData

Reference for workerData in Node.js worker_threads: pass a cloned value to a new Worker at startup, what can be cloned, transfers, DataCloneError and alternatives.

workerData is the value you hand to a worker at creation time. In the parent you pass it as options.workerData to new Worker(); inside the worker you import the same name from node:worker_threads and read it as an ordinary constant. It is available from the very first line of the worker's code, so there is no waiting for a message.

The value is copied with the structured clone algorithm, the same one used by postMessage() and structuredClone(). The worker therefore gets its own independent copy: changing it there does not change the parent's object. In the main thread, workerData is null.

NODE
import { Worker, isMainThread, workerData } from 'node:worker_threads';

if (isMainThread) {
  new Worker(import.meta.filename, { workerData: { from: 1, to: 100 } });
} else {
  console.log(workerData.from, workerData.to);
}

Try it

Node.js A copy, not a shared object

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js What cannot be cloned, and transferring

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What you can pass

Allowed Not allowed
Primitives, plain objects, arrays Functions and methods
Date, RegExp, Map, Set, Error Class instances: they are cloned, but only own data properties survive; the prototype and methods are lost (the copy is a plain object)
ArrayBuffer, typed arrays, DataView, Buffer (as Uint8Array) Symbols as values
SharedArrayBuffer (shared, never copied) Handles such as sockets, fs.FileHandle (except where documented), streams
MessagePort (only through transferList) Promise, WeakMap, WeakSet

An unclonable value makes the new Worker() call throw a DataCloneError (a DOMException) synchronously, as the second example shows.

Usage notes

  • Read it once, at the top. workerData never changes after startup. For later communication use parentPort.postMessage(); for data shared by many workers see setEnvironmentData().
  • Transfer big buffers. Put an ArrayBuffer (or MessagePort) in options.transferList to move it; the parent's reference becomes detached with byteLength === 0. For true sharing use a SharedArrayBuffer. See Transferring and sharing memory.
  • Keep it small. The clone happens synchronously in the parent before the worker starts. Passing a 200 MB object delays your main thread and doubles memory. Read big inputs from a file in the worker, passing only the path.
  • A Buffer arrives as a Uint8Array. Wrap it again with Buffer.from(workerData.buf.buffer, workerData.buf.byteOffset, workerData.buf.byteLength) if you need Buffer methods.
  • workerData is null in the main thread. Check isMainThread before using it. See isMainThread and parentPort.
  • Not for secrets in logs. Values appear in heap snapshots and error reports of the worker like any other data.
  • Per-task data in pools. A worker pool reuses workers, so per-task input must be sent as messages; workerData only configures the pool member itself.