Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import { setEnvironmentData, getEnvironmentData } from 'node:worker_threads';

setEnvironmentData('logLevel', 'debug');
console.log(getEnvironmentData('logLevel'));   // 'debug'

Try it

Node.js Configuration for every worker

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 Copies, deleting and nested workers

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

NODE
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. Call setEnvironmentData() again to change what future children inherit.
  • Compare with workerData. workerData is 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 from process.env.
  • Available in the main thread too. You can read back what you set there, for example in tests.