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.
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
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.
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.
workerDatanever changes after startup. For later communication useparentPort.postMessage(); for data shared by many workers seesetEnvironmentData(). - Transfer big buffers. Put an
ArrayBuffer(orMessagePort) inoptions.transferListto move it; the parent's reference becomes detached withbyteLength === 0. For true sharing use aSharedArrayBuffer. 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
Bufferarrives as aUint8Array. Wrap it again withBuffer.from(workerData.buf.buffer, workerData.buf.byteOffset, workerData.buf.byteLength)if you needBuffermethods. workerDataisnullin the main thread. CheckisMainThreadbefore using it. SeeisMainThreadandparentPort.- 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;
workerDataonly configures the pool member itself.