Node-RED Environment Variable Reader

1.0.2 · active · verified Sun Apr 19

This package provides a dedicated Node-RED node (`process-env`) for retrieving environment variables from the server process where Node-RED is executing. It serves as a fundamental utility for integrating Node-RED flows with their host environment, enabling external configuration without modifying the flow directly. The node, currently at stable version 1.0.2, simplifies accessing `process.env` values compared to using a generic Function node. Its release cadence is typically driven by bug fixes or minor compatibility updates. A key differentiator is its straightforward configuration within the Node-RED editor, allowing users to specify the environment variable key directly or infer it from incoming message properties (`payload` or `topic`), with a clear order of precedence. This makes it a go-to solution for parameterizing Node-RED applications.

Common errors

```
Cannot read property 'env' of undefined
```
cause The Node-RED runtime environment, or the way `process.env` is accessed by the node, might be misconfigured or the Node.js `process` global object is unavailable in a specific context.

fix Ensure Node-RED is running in a standard Node.js environment where `process.env` is accessible. This error is rare for this specific node unless the Node-RED installation itself is corrupted or running in an unusual sandbox.
```
msg.payload is undefined (or null) after process-env node
```
cause The environment variable specified in the node configuration (or via `msg.payload`/`msg.topic`) was not found in the Node-RED server's `process.env`.

fix Verify that the environment variable is correctly set in the operating system or environment where Node-RED is launched (e.g., `export MY_VAR=value` in shell, `Environment=` in `systemd`, or defined in Docker Compose). Double-check for typos in the variable name within the node's configuration. Use a Debug node before the `process-env` node to ensure `msg.payload` or `msg.topic` contains the expected variable name if those inputs are being used.

Warnings

gotcha Environment variables are read from the Node-RED server process at startup, not from the browser running the editor. Changes to environment variables require a Node-RED restart to take effect.
Fix: Restart the Node-RED instance after modifying environment variables to ensure the changes are picked up by the runtime. For Docker, this means restarting the container.
gotcha The node determines the environment variable key using a specific precedence: first, the `key` configured in the node's properties; second, `msg.payload`; and third, `msg.topic`. If all three are present, the node's `key` property takes priority. This can lead to unexpected behavior if multiple sources are used simultaneously.
Fix: Clearly define a single source for the environment variable key to avoid ambiguity. If you intend to use `msg.payload` or `msg.topic`, ensure the node's `key` property is left blank. Alternatively, use a preceding Change node to normalize the incoming message if necessary.
gotcha Unlike some other Node-RED mechanisms (e.g., Change node's `$env()` function, TypedInput widget with `${VAR}` syntax), this specific `process-env` node does not support dynamic updates of environment variables during flow execution. The values are resolved when the node is processed.
Fix: If dynamic access to environment variables within a flow is required, consider using a Function node with `process.env.MY_VAR`, or Node-RED's built-in `$env()` function in Change nodes or `env.get()` in Function nodes, which are also evaluated at runtime. For configuration that truly needs to change at runtime *without* a Node-RED restart, consider using flow or global context, or external databases/APIs, rather than environment variables.

Install

npm install node-red-contrib-env npm
yarn add node-red-contrib-env yarn
pnpm add node-red-contrib-env pnpm

Imports

node-red-contrib-env
wrong:
```
import { EnvNode } from 'node-red-contrib-env';
```
correct:
```
npm install node-red-contrib-env
```
Node-RED 'contrib' packages are installed via npm/yarn into the Node-RED runtime and appear in the editor palette; they are not imported directly into user JavaScript code like a typical library.
Node-RED palette
```
Add 'process-env' node from the palette in Node-RED editor.
```
After installation, the 'process-env' node becomes available in the Node-RED editor's palette under the 'utility' category for drag-and-drop use.

Quickstart

This Node-RED flow demonstrates reading an environment variable. First, ensure the environment variable `MY_ENV_VAR` is set in the Node-RED server's environment (e.g., `export MY_ENV_VAR='Hello from Env!'` before starting Node-RED). The Inject node triggers the flow. The 'Read MY_ENV_VAR' node (`process-env` type) is configured to look for a variable named `MY_ENV_VAR`. The Debug node displays the retrieved value (or `undefined` if not found) in the Node-RED debug sidebar.

[{"id":"e05f2e82f7169f4b","type":"inject","z":"0453347f311c6264","name":"Trigger","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payloadType":"date","x":120,"y":80,"wires":[["715d31518f888f4c"]]},{"id":"715d31518f888f4c","type":"process-env","z":"0453347f311c6264","name":"Read MY_ENV_VAR","key":"MY_ENV_VAR","x":340,"y":80,"wires":[["ed27fb47184209c1"]]},{"id":"ed27fb47184209c1","type":"debug","z":"0453347f311c6264","name":"Debug Output","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":570,"y":80,"wires":[]}]

view raw JSON →