Environment & Config

Reviewed & published by Brayan K

Configuration is the set of values that change between machines — ports, database URLs, API keys — which you keep out of your code and read from environment variables on process.env.

Part of the free Node.js course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

By the end of this lesson you'll read environment variables with sensible defaults, load a .env file natively, convert string values to the right types, and centralize everything in a validated config module.

What You'll Learn in This Lesson

• Why config belongs in env vars, not in your code
• Reading values from process.env with defaults
• Why every env value is a string (and how to convert)
• Loading a .env file with --env-file
• Keeping secrets safe with .gitignore
• Centralizing and validating config in one module

1️⃣ Reading process.env

Node puts every environment variable on the process.env object. Read a value, supply a default with ?? for when it's missing, and remember that every value is a string — convert with Number() when you need a number.

// Configuration that changes between machines — ports, secrets, database URLs —
// should NOT be hard-coded. Node exposes ENVIRONMENT VARIABLES on process.env.

// process.env is an object of strings provided by the operating system.
console.log("PORT from env:", process.env.PORT);     // -> undefined if not set

// Provide a sensible DEFAULT with the ?? operator (used when env is undefined).
const port = process.env.PORT ?? 3000;
console.log("Using port:", port);

// IMPORTANT: every value in process.env is a STRING. Convert when you need a number.
const workers = Number(process.env.WORKERS ?? "1");
console.log("Workers (a number):", workers, typeof workers);

// You set variables when you launch the program, e.g.:
//   PORT=8080 WORKERS=4 node app.js
// then process.env.PORT is "8080".

2️⃣ Loading a .env File

Typing variables on every launch gets old. A .env file holds KEY=value lines, and recent Node loads it natively with --env-file. Keep that file out of git so secrets stay private.

// Typing variables on every launch is tedious. The common pattern is a .env
// FILE holding key=value lines, loaded at startup.

// A file named ".env" in your project root might contain:
//   PORT=8080
//   DB_URL=sqlite://app.db
//   API_KEY=super-secret-123

// Node v20.6+ can load it natively with the --env-file flag (no package):
//   node --env-file=.env app.js

// After loading, the keys appear on process.env like any other variable.
// There is no .env file behind the Run button, so these two lines stand in
// for what --env-file would have put there. Remove them and the ?? defaults
// below take over, which is exactly what happens when the file is missing —
// worth trying, because that silent fallback is the usual cause of "why is
// it still on port 3000?".
process.env.PORT = "8080";
process.env.DB_URL = "sqlite://app.db";

const port = process.env.PORT ?? 3000;
const dbUrl = process.env.DB_URL ?? "sqlite://default.db";

console.log("Port:", port);
console.log("DB:", dbUrl);

// 🔒 Add .env to your .gitignore so secrets never get committed to git.

3️⃣ A Central, Validated Config Module

Reading process.env scattered across files gets messy. The clean pattern: a single config.js that reads, validates, and exports one object. Required values throw at startup if missing, so the app fails fast instead of breaking mysteriously later.

// Best practice: read env vars ONCE in a single config module, validate them,
// and export a clean object. The rest of your app imports config — not process.env.

// --- config.js ---
function required(name) {
  const value = process.env[name];
  // Fail FAST and LOUD if a required value is missing.
  if (value === undefined) {
    throw new Error(`Missing required env var: ${name}`);
  }
  return value;
}

// The Run button sets no environment at all, so give the required key a
// value first. Without it the very first thing this module does is throw —
// which is precisely what it is built to do, and what you want on a real
// server: a config error should stop the process at boot, not surface as a
// confusing 500 an hour later.
process.env.API_KEY = "super-secret-123";

const config = {
  port: Number(process.env.PORT ?? 3000),     // optional, with default
  env: process.env.NODE_ENV ?? "development",
  apiKey: required("API_KEY"),                 // required: throws if absent
};

module.exports = config;

// --- app.js ---
// const config = require("./config");
// console.log("Starting on port", config.port, "in", config.env, "mode");

console.log("port:", config.port, "env:", config.env);

// Never printed: the API key itself. Logging secrets is how they end up in
// a log aggregator that half the company can read.

// Now watch the loud failure. Ask for a variable that really is absent,
// caught here only so the rest of this block still runs — in a real app you
// would let it crash the process:
try {
  required("STRIPE_KEY");
} catch (err) {
  console.log("missing var ->", err.message);
}

Your turn. Fill in the two ___ blanks to read a host and port with defaults, then run it.

// 🎯 YOUR TURN — finish the config, then run: node app.js
// (try it with:  HOST=example.com node app.js  and also with no env set)

// TODO 1: read process.env.HOST, defaulting to "localhost" when it's missing.
const host = process.env.HOST ?? ___;        // 👉 the default host string

// TODO 2: read process.env.PORT, default 3000, and convert it to a NUMBER.
const port = ___(process.env.PORT ?? "3000"); // 👉 the function that makes a number

console.log(`Server would run at http://${host}:${port}`);

// ✅ With no env set:
//    Server would run at http://localhost:3000
// ✅ With HOST=example.com PORT=8080:
//    Server would run at http://example.com:8080

Mini-Challenge: A Validated Config Module

Build a real config.js with a required() helper, a number, a required string, and a boolean parsed from a string. Import it in app.js and print all three values.

// 🎯 MINI-CHALLENGE: a validated config module.
// Save as config.js (and a small app.js) and run: node --env-file=.env app.js
//
// 1. Write a helper required(name) that returns process.env[name],
//    or throws "Missing env var: NAME" when it's undefined.
// 2. Build a config object with:
//      port:   Number(process.env.PORT ?? 4000)
//      dbUrl:  required("DB_URL")
//      debug:  process.env.DEBUG === "true"   // string -> boolean
// 3. Export it with module.exports, import it in app.js, and print all three.
//
// ✅ With a .env of  DB_URL=sqlite://x.db  and  DEBUG=true :
//    port: 4000  dbUrl: sqlite://x.db  debug: true

// your code here

Common Errors (and the fix)

• Math gives the wrong answer — You treated an env string as a number. process.env.PORT + 1 is "30001", not 3001. Wrap it in Number() first.
• A "false" flag is truthy — The string "false" is truthy in JS. Compare explicitly: process.env.DEBUG === "true".
• .env not loaded — You forgot --env-file=.env (or, on old Node, require("dotenv").config() at the top). Then process.env stays empty.
• Secret committed to git — You forgot to add .env to .gitignore. Add it, rotate the secret, and commit a .env.example instead.
• App crashes deep inside instead of at startup — Validate required vars at boot and throw a clear message, so missing config fails immediately.

Pro Tips

• 💡 One source of truth: read process.env only inside config.js; everything else imports the config object.
• 💡 Commit a template: a .env.example with empty values documents what's needed without leaking secrets.
• 💡 Use NODE_ENV: the convention development / production lets you switch behavior, like logging detail.

📋 Quick Reference — Config in Node

🎉 Lesson Complete!

• ✅ Config lives in environment variables, never hard-coded
• ✅ Read them from process.env, with ?? defaults
• ✅ Every env value is a string — convert numbers and booleans
• ✅ Load a .env file with --env-file
• ✅ Keep .env in .gitignore; validate required vars at startup

Practice quiz

Continue this course

• Previous: Connecting a Database
• Next: Testing (node:test) — Write automated tests with the built-in node:test runner
• Quick reference: Node.js cheat sheet › Core Modules (fs, path, http)

Frequently asked questions

What is process.env and why use it?

process.env is an object Node fills with the environment variables provided by your operating system or launch command. It's the standard place to keep configuration that differs between environments — the port to listen on, a database URL, an API key — without baking those values into your source code. That separation lets the exact same code run on your laptop, a teammate's machine, and a production server, each supplying its own values. It also keeps secrets out of the files you commit to version control.

Why is everything in process.env a string?

Environment variables come from the operating system, which only knows text — there's no concept of a number or boolean at that layer. So process.env.PORT is the string "3000", not the number 3000, and process.env.DEBUG is "true", not the boolean true. You must convert explicitly: Number(process.env.PORT) for numbers, and a comparison like process.env.DEBUG === "true" for booleans. Forgetting this leads to subtle bugs, such as string concatenation where you expected arithmetic.

Do I need the dotenv package to use a .env file?

Not anymore. Node.js version 20.6 and later can load a .env file natively with the --env-file flag: node --env-file=.env app.js reads the file and populates process.env before your code runs. On older Node versions, the popular dotenv package does the same thing — you call require("dotenv").config() at the very top of your entry file. Either way, a .env file is just a convenience so you don't have to type variables on the command line every time.

How do I keep secrets like API keys safe?

Never commit them. Put secrets in environment variables or a .env file, and add .env to your .gitignore so it's never pushed to a repository. Commit a .env.example file instead, listing the variable names with placeholder values, so teammates know what to set without seeing the real secrets. In production, set the variables through your hosting platform's configuration rather than a file. And validate required secrets at startup so the app fails loudly if one is missing, rather than misbehaving later.