Node.js process.env: Read Environment Variables

process.env is an object with one property per environment variable that the shell passed to your Node.js program: process.env.PORT, process.env.DATABASE_URL, and so on. A variable that was not set reads as undefined, and a variable that was set is always a string. Read it once at startup, give it a default, and convert it to the type you need.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

It printed shop on port 8080 in eu-west (REGION was never set, so its default took over), then string number: the variable is text until Number() converts it. Delete the first two assignments and run again to see every default.

Set environment variables in the shell

The variables come from wherever Node.js is started. In a terminal:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

Hosting platforms (Heroku, Render, Vercel, Docker, Kubernetes) have a settings page or file for the same thing; your code reads them the same way.

Everything is a string

This is where most process.env bugs come from. 'false' and '0' are non-empty strings, so they are truthy:

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

The naive check printed debug is ON for a variable set to false, so compare against the exact string you expect. For numbers, Number(process.env.X) turns a missing value into NaN, so apply the default before converting, as the first example did with ??.

NODE_ENV

NODE_ENV is a convention, not a Node.js feature: Node.js never sets it. Libraries read it. Express, for one, hides stack traces from error pages when it is production, and many tools skip development-only checks.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

It printed mode: production and verbose logs: false; change 'production' to 'development' and the second line flips. Stick to production, development and test, because libraries check for those exact words.

.env files: --env-file and dotenv

Typing every variable before node gets old. A .env file keeps them in your project folder, one per line:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 and later read it with a flag, no package needed:

node --env-file=.env app.js

On older versions, or if you prefer it, install the dotenv package (npm install dotenv) and load it at the very top of your entry file, before any code reads process.env:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

Neither one overwrites a variable that is already set in the shell, so production settings win over the file.

Fail early on missing variables

A missing database URL should stop the program at startup with a clear message, not crash on the first request an hour later:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

It printed Missing environment variables: API_KEY; add process.env.API_KEY = 'test'; at the top and it prints Config OK. In a real program, follow the message with process.exit(1), because a nonzero exit code is how a deploy script or a container platform sees that startup failed.

Never commit secrets

Put .env in .gitignore the day you create it. Commit a .env.example with the variable names and fake values instead, so others know what to set. A key that was ever pushed to a repository should be treated as leaked and replaced, even if you delete the commit later.