Settings from Environment Variables

A setting that changes from one computer to another, such as where a data folder is, belongs in an environment variable, which a Node program reads from process.env with a default from ??, and which comes from the terminal or from an .env file loaded with node --env-file.

Apprentice · Node.js · JavaScript · Updated

By

After this lesson you can

  • Read a setting from process.env, with a default from the nullish coalescing operator (??)
  • Set an environment variable in PowerShell or zsh, or in an .env file loaded with node --env-file, and keep .env out of Git

Key takeaways

  • An environment variable is a named setting the computer hands to every program it starts. Node shows them in process.env, always as text.
  • A variable that isn't set is undefined, so give it a default with ?? (read "nullish coalescing"), such as process.env.RUNLOG_DIR ?? "data".
  • ?? uses the default only for undefined or null; || also replaces an empty string and 0, which can throw away a real setting.
  • Set one for the terminal with $env:NAME = "value" in PowerShell, or for one command with NAME=value in front of it in zsh.
  • node --env-file=.env loads NAME=value lines from a file, with no package needed. Keep .env out of Git, because it often holds secrets.

Every server you'll build in this course reads settings the same way: the port to listen at, the address of its database, a secret key that must never be in the code. They differ from your laptop to a test server to the live one, and none of them should be typed out every time the program starts. Environment variables are where those settings live, and the club's report is a good place to meet them.

Dana keeps the club's log in a data folder. Leo keeps his copy in a folder named club-data. The report could take a --folder option, but they'd type it on every run, and the folder is a fact about each person's computer, not about one report.

Settings the computer hands every program: process.env

An environment variable is a named setting the computer hands to every program it starts. You already have dozens of them; PATH, the list of folders the terminal searches for commands, is one. Node shows them all in process.env, one property for each:

console.log(process.env.RUNLOG_DIR);
undefined

Nobody has set RUNLOG_DIR yet, so it's undefined. Its name is the club's own choice; by habit, environment variable names are written in capitals, with underscores between the words.

A default with ?? (nullish coalescing)

When the variable isn't set, the report should use data. The ?? operator, read "nullish coalescing", picks its right side only when its left side is undefined or null (together, the "nullish" values). Here's folder.js:

const folder = process.env.RUNLOG_DIR ?? "data";
console.log(`Reading the log from: ${folder}`);
Reading the log from: data

You may see || (read "or") used for defaults in older code. It also replaces "" and 0, which can be real settings:

const empty = "";
const zero = 0;

console.log(empty ?? "data");
console.log(zero ?? 20);
console.log(empty || "data");
console.log(zero || 20);

0
data
20

The first line printed is the empty string, kept by ??. With ||, someone who sets a weekly goal of 0 gets 20 instead.

Every environment variable is text, even WEEKLY_GOAL=25: process.env.WEEKLY_GOAL + 5 is "255". Turn it into a number with Number() first.

Setting one in the terminal

Each shell has its own way. In PowerShell, $env:NAME = "value" sets a variable for the rest of that terminal's life, and every program you start from it sees the setting:

$env:RUNLOG_DIR = "club-data"
node folder.js
Reading the log from: club-data

Remove-Item Env:RUNLOG_DIR takes it away again, and closing the terminal forgets it too. In zsh on a Mac, put NAME=value in front of a command to set it for that one command, or export NAME=value to set it for the rest of the terminal's life:

RUNLOG_DIR=club-data node folder.js
Reading the log from: club-data

Settings in a file: node --env-file

Typing settings into every new terminal gets old. Put them in a file named .env (read "dot env") beside your program, one NAME=value per line:

RUNLOG_DIR=club-data
WEEKLY_GOAL=25

Then start Node with --env-file, and it loads the file into process.env before your code runs:

node --env-file=.env folder.js
Reading the log from: club-data

You may see older projects install a package named dotenv for this; Node has done it on its own since version 20. If the file isn't there, Node stops at once with .env: not found. A variable that's already set in the terminal wins over the same name in the file, so you can override one setting for one run.

Keep .env out of Git. Add a line .env to your project's .gitignore. An .env file soon holds a database password or a secret key, and a secret that reaches GitHub has to be changed everywhere it's used. Keeping Secrets Out of Your Code, in Module 4, goes further.

Check yourself

2 questions to try on the lesson page.

So what

Facts about each computer, such as a folder, a port or a secret, go in environment variables with a sensible default, so the same code runs on Dana's laptop, Leo's and, later, a server online, unchanged.

Key terms

Related