If you've been hardcoding API keys in your JavaScript files, you're one public GitHub push away from a bad day.

I'm Jeffrey — I run a web design agency called Velto and I'm currently 16 weeks deep into learning Express.js properly, starting from the JavaScript foundations most tutorials skip.

The problem environment variables solve

When your app runs, it needs configuration: what port to listen on, what database to connect to, what API keys to use. The naive approach is hardcoding these values directly in your code:

js
const PAYSTACK_KEY = "sk_live_xxxxxxxxxxx";
const DB_URL = "postgresql://jeffrey:password@localhost:5432/velto";

This creates two immediate problems.
First, security. If this code ever touches a version control system — especially a public one — those secrets are exposed. GitHub has bots scraping repos for leaked credentials around the clock. This is not paranoia. It happens.
Second, portability. Your local database URL is different from your production database URL. Your dev Paystack key is different from your live one. If these values are in your code, you're changing code every time you deploy. That's a broken workflow.
Environment variables are the solution. Instead of values in your code, you store them in the environment where your code runs — your OS, your shell session, or your hosting platform. Your code reads them at runtime using process.env.

process.env

Node.js exposes all environment variables through a global object called process.env. No imports, always available.

js
console.log(process.env.HOME); // /home/jeffrey
console.log(process.env.PATH); // long string of directories
You can set variables in your terminal session:
bashexport MY_SECRET=hello123
node -e "console.log(process.env.MY_SECRET)" // hello123

But that's tedious and they disappear when you close the terminal. For a real project, you use a .env file.

The .env file

A .env file is a plain text file at your project root. One key=value pair per line:

PORT=3000
DATABASE_URL=postgresql://jeffrey:password@localhost:5432/velto_db
JWT_SECRET=long_random_string_here
PAYSTACK_SECRET_KEY=sk_live_xxxxxx
NODE_ENV=development

Important syntax rules:
No spaces around =
No quotes needed unless the value contains spaces
Comments with #
Never use commas or semicolons

This file never gets committed to version control. Add it to .gitignore before you write anything else.
dotenv — what it actually does

dotenv is a small npm package that reads your .env file and injects the values into process.env at runtime.

bash
npm install dotenv

js
require('dotenv').config(); // This must be the first thing that runs

Here's the internal logic of what .config() does:

Finds .env in the current working directory
Parses each line as KEY=VALUE
For each key, if process.env.KEY is not already set, it adds it
Returns { parsed: { ... } } with what it loaded

That third step is crucial. dotenv does not overwrite existing environment variables. This is intentional. On your hosting platform (Render, Railway, etc.), variables are set at the system level before your app starts. dotenv won't touch them. Your production config always wins.

The .env.example pattern

Since .env is gitignored, you need a way to communicate what variables are required. The standard solution: .env.example. A copy with values blanked out. This one you DO commit.

PORT=
NODE_ENV=
DATABASE_URL=
JWT_SECRET=
PAYSTACK_SECRET_KEY=
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

Anyone cloning the repo knows exactly what to fill in.
A config module — the pattern worth copying
Instead of sprinkling process.env.WHATEVER throughout your codebase, centralize it:

js
// config.js
require('dotenv').config();

const config = {
  port: process.env.PORT || 3000,
  nodeEnv: process.env.NODE_ENV || 'development',
  jwtSecret: process.env.JWT_SECRET,
  databaseUrl: process.env.DATABASE_URL,
  paystackKey: process.env.PAYSTACK_SECRET_KEY,
};

// Crash loud if required variables are missing
const required = ['jwtSecret', 'databaseUrl', 'paystackKey'];
required.forEach((key) => {
  if (!config[key]) {
    throw new Error(`Missing required env variable: ${key}`);
  }
});

module.exports = config;

This pattern:
Gives you one place to see all your config
Validates required variables at startup instead of silently failing later
Makes it easy to set default values
Keeps process.env out of your business logic

The gotchas
Env vars are always strings. MAINTENANCE_MODE=true in your .env is the string "true", not a boolean. Convert explicitly:

js
const maintenanceMode = process.env.MAINTENANCE_MODE === 'true';

dotenv reads once at startup. Change .env, nothing updates until you restart the server.
Don't log process.env. It dumps every secret to your terminal, and in production those logs can be stored and accessed elsewhere.
Always fallback on PORT. Platforms like Render assign PORT dynamically. process.env.PORT || 3000 ensures your app starts whether you're local or on a server.

The build
Here's a minimal Express app that demonstrates all of this:

env-demo/
  .env
  .env.example
  .gitignore
  server.js
  package.json

.env:
PORT=3000
APP_NAME=Velto API
SECRET_MESSAGE=This came from your environment
MAINTENANCE_MODE=false

server.js:
js
require('dotenv').config();

const express = require('express');
const app = express();

app.use(express.json());

const PORT = process.env.PORT || 3000;
const APP_NAME = process.env.APP_NAME || 'My API';
const SECRET_MESSAGE = process.env.SECRET_MESSAGE;
const MAINTENANCE_MODE = process.env.MAINTENANCE_MODE === 'true';

// Maintenance middleware — checks on every request
app.use((req, res, next) => {
  if (MAINTENANCE_MODE) {
    return res.status(503).json({
      status: 'error',
      message: 'Down for maintenance.',
    });
  }
  next();
});

app.get('/', (req, res) => {
  res.json({
    app: APP_NAME,
    environment: process.env.NODE_ENV || 'development',
    status: 'running',
  });
});

app.get('/secret', (req, res) => {
  if (!SECRET_MESSAGE) {
    return res.status(500).json({ error: 'SECRET_MESSAGE not configured.' });
  }
  res.json({ message: SECRET_MESSAGE });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

app.listen(PORT, () => {
  console.log(`[${APP_NAME}] Listening on port ${PORT}`);
});

Try: flip MAINTENANCE_MODE=true, restart, hit any route. All 503. Flip it back. Normal again. That's real feature-flag behavior with zero code changes.

Remove SECRET_MESSAGE from your .env, restart, hit /secret. The missing variable is handled gracefully. Your app doesn't crash silently or expose undefined as a response.

In production
On Render, you never upload a .env file. Go to your service → Environment tab → add variables there. Render injects them before your app starts. dotenv effectively becomes a no-op in production — variables are already in process.env. That's the design working correctly.

I'm documenting every step of this 16-week Express.js journey publicly. Next up: routing and middleware — the actual backbone of how Express works.