Environment Variables
Environment variables are named values supplied to a program by the system it runs on, rather than written into the code. In a Node.js and Express app, they hold settings that change between your laptop and the production server, and secrets that must never be committed to Git: the port number, database connection strings, JWT secrets and API keys. Node exposes them on the process.env object.
Reading values from process.env
Every value in process.env is a string, or undefined if the variable was not set. Read them once, near the start of the app, and supply safe defaults only for non-secret settings.
// config.js
const port = Number(process.env.PORT) || 3000;
const mongoUri = process.env.MONGODB_URI;
const jwtSecret = process.env.JWT_SECRET;
const isProduction = process.env.NODE_ENV === 'production';
if (!mongoUri || !jwtSecret) {
console.error('Missing MONGODB_URI or JWT_SECRET');
process.exit(1);
}
module.exports = { port, mongoUri, jwtSecret, isProduction };
Failing fast at startup is much better than discovering a missing secret when the first user tries to log in.
Using a .env file in development
Typing variables into the terminal each time is tedious, so most projects keep them in a .env file in the project root. Node 20.6 and later can load it directly with a flag, or you can use the popular dotenv package.
# .env (never commit this file)
PORT=4000
MONGODB_URI=mongodb://127.0.0.1:27017/shop
JWT_SECRET=change-me-to-a-long-random-string
# .gitignore
.env
# Start the app, built-in loader
node --env-file=.env server.js
# Or with dotenv: npm install dotenv, then at the very top of server.js
# require('dotenv').config();
Commit a .env.example file with the same keys and dummy values, so teammates know which variables the app expects.
Setting variables in production
On a hosting platform, you do not upload a .env file. Instead you enter the variables in the platform's dashboard or CLI, and they are injected into the process when it starts. Many platforms set PORT for you, which is why your server must read it instead of hard-coding a number.
Mistakes that leak secrets or break config
The most serious one is committing .env to Git. Even if you delete it later, it stays in the history, and anyone with access to the repository can read it. If that happens, treat the secrets as exposed and change them. Add .env to .gitignore before the first commit.
A second is forgetting that values are strings. process.env.DEBUG = 'false' is a non-empty string and therefore truthy, so if (process.env.DEBUG) runs anyway. Compare explicitly: process.env.DEBUG === 'true'. Convert numbers with Number().
A third is loading dotenv too late. If another module reads process.env while being imported before dotenv.config() runs, it sees undefined. Call it at the very first line of the entry file, or use the --env-file flag.
Finally, frontend build tools also have "environment variables", such as VITE_API_URL, but those are baked into public JavaScript files. Never put secrets there.
Keep variable names consistent and descriptive, in capital letters with underscores, such as SMTP_HOST or PAYMENT_SECRET_KEY. Reading every variable in one config module, as in the first example, also means the rest of the code imports plain values and never touches process.env directly, which makes testing easier.
What to remember
- Configuration that changes per environment goes in
process.env. - Keep
.envout of Git; share a.env.exampleinstead. - Validate required variables at startup.
- All values are strings; convert and compare carefully.
Ready to master real-world web development?
Learn HTML, CSS3, Bootstrap and JavaScript hands-on with mentor-led sessions.