Node.js Reference ยท child_process, worker_threads and cluster
Node.js setEnvironmentData() and getEnvironmentData()
Reference for worker_threads setEnvironmentData() and getEnvironmentData() in Node.js: share configuration with every new Worker, cloning rules and inheritance.
setEnvironmentData(key, value) stores a value under a key in the current thread's "environment data". Every Worker created afterwards receives a clone of that data, and can read entries with getEnvironmentData(key). It is a convenient way to hand the same configuration, such as a log level or a feature flag, to many workers without repeating workerData in every constructor call.
The key point is when the copy happens: at the moment a worker is created. Later calls to setEnvironmentData() in the parent do not change workers that already exist. A worker can also set its own entries, and the workers it starts inherit them.
import { setEnvironmentData, getEnvironmentData } from 'node:worker_threads'; setEnvironmentData('logLevel', 'debug'); console.log(getEnvironmentData('logLevel')); // 'debug'
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.
Syntax
setEnvironmentData(key: any, value?: any): void getEnvironmentData(key: any): any
| Name | Description |
|---|---|
key |
Any value that can be compared with === after cloning. Strings are the practical choice. Keys of other types, such as numbers, are allowed. |
value |
Any value the structured clone algorithm accepts (see workerData). Passing undefined, or omitting it, deletes the entry. |
Returns: setEnvironmentData() returns nothing; getEnvironmentData() returns the stored value, or undefined if the key does not exist.
Errors: a value that cannot be cloned makes the next new Worker() throw a DataCloneError; the error appears at worker creation, not at the setEnvironmentData() call.
Usage notes
- Snapshot at creation time. Each new worker gets a clone of the creator's environment data as it is at that moment. Existing workers never see later changes.
- Per-thread, not global. Every thread has its own environment data. A change in a worker is visible to that worker and to the workers it creates afterwards, never to its parent or siblings.
- Values are clones. Mutating an object obtained from
getEnvironmentData()changes only the local copy. CallsetEnvironmentData()again to change what future children inherit. - Compare with
workerData.workerDatais passed once per worker and is private to it. Environment data is inherited by every later worker, including nested ones, which makes it better for process-wide configuration. - Do not use it for secrets or large data. The data is cloned for every worker you create, so big values slow down worker start-up and use memory in every thread.
- Not the same as
process.env. Environment variables are strings and belong to the process (workers get a copy by default). Environment data accepts any cloneable value and is separate fromprocess.env. - Available in the main thread too. You can read back what you set there, for example in tests.