🔑 Environment Variables

Why Config Lives Outside Code

An environment variable is a value the operating system (or your tooling) hands to a running process. It is not compiled in — it is supplied from the outside, so the same build behaves differently depending on where it runs.

Think of the dials on the outside of an oven. You can raise the temperature without opening the oven or rebuilding it. Environment variables are those dials for your app: the code (the oven) stays sealed, while the settings (the dials) change per environment. This is the config principle from the Twelve-Factor App methodology, and it buys you four things at once:

• Security — secrets like API keys and DB passwords never sit in source code
• Per-environment config — dev, staging, and prod each get their own values
• Deploy flexibility — change a value without rebuilding or editing code
• Container friendliness — Docker and cloud platforms inject config exactly this way

Why it matters: hardcode mongodb://localhost and your app cannot ship. Hardcode a secret and it lives in your Git history forever. Externalizing config is the difference between a demo and a deployable application.

Server-Side: dotenv & process.env

In Node.js, environment variables arrive on the global process.env object as strings. In development you rarely set them by hand — you put them in a .env file and load them with the dotenv package.

The .env file

// .env  (project root — NEVER committed to Git)
NODE_ENV=development
PORT=3001
DATABASE_URL=mongodb://localhost:27017/myapp
JWT_SECRET=super-secret-change-me
CORS_ORIGINS=http://localhost:5173

Loading it — first line of your entry file

// server.js — load env vars BEFORE anything else reads them.
require('dotenv').config();

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

// process.env values are always STRINGS — parse numbers/booleans yourself.
const port = parseInt(process.env.PORT, 10) || 3001;

app.get('/', (req, res) => {
  res.send(`Running in ${process.env.NODE_ENV} mode`);
});

app.listen(port, () => console.log(`API on port ${port}`));

A Central Config Module

Sprinkling process.env.WHATEVER throughout your codebase scatters defaults and makes typos silent. The professional pattern is one config module that reads, parses, validates, and re-exports everything. The rest of the app imports that, never process.env directly.

// config.js — the single source of truth for configuration.
require('dotenv').config();

// Fail fast: if a required secret is missing, crash at startup
// with a clear message instead of a mysterious error at 3am.
const required = ['DATABASE_URL', 'JWT_SECRET'];
const missing = required.filter((key) => !process.env[key]);
if (missing.length > 0) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

module.exports = {
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT, 10) || 3001,
  databaseUrl: process.env.DATABASE_URL,
  jwtSecret: process.env.JWT_SECRET,
  // Turn a comma-separated string into a real array for the CORS allowlist.
  corsOrigins: (process.env.CORS_ORIGINS || 'http://localhost:5173')
    .split(',')
    .map((o) => o.trim()),
  debug: process.env.DEBUG === 'true' // explicit string compare
};

// server.js — clean, and every value is already parsed and validated.
const config = require('./config');
const express = require('express');
const cors = require('cors');

const app = express();
app.use(cors({ origin: config.corsOrigins, credentials: true }));

app.listen(config.port, () =>
  console.log(`Server running in ${config.env} mode on port ${config.port}`)
);

Client-Side: Vite & import.meta.env

Frontend code runs in the browser, not on a server, so there is no process.env at runtime. Instead, your build tool bakes selected variables into the bundle at build time. In Vite you read them from import.meta.env, and only variables prefixed with VITE_ are exposed.

// .env  (in the frontend project)
VITE_API_URL=http://localhost:3001/api
VITE_FEATURE_NEW_UI=true

// Anywhere in your Vite app — note import.meta.env, not process.env.
const API_URL = import.meta.env.VITE_API_URL;

async function getUsers() {
  const res = await fetch(`${API_URL}/users`);
  if (!res.ok) throw new Error('Failed to load users');
  return res.json();
}

// Booleans arrive as strings here too — compare explicitly.
const newUiEnabled = import.meta.env.VITE_FEATURE_NEW_UI === 'true';

Frontend Vars Are Never Secret

This is the single most important idea in the lesson, and the one beginners get wrong. A VITE_ variable is baked into the JavaScript bundle that ships to every visitor. Anyone can open DevTools, view the source, and read it. There is no such thing as a secret frontend environment variable.

// ❌ NEVER — this secret is now readable by every visitor.
const stripeSecret = import.meta.env.VITE_STRIPE_SECRET_KEY;

// ✅ Correct — the secret stays on the server; the browser calls
// your own endpoint, and the server talks to Stripe with the secret.
async function pay(amount) {
  const res = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount })
  });
  return res.json();
}

Why it matters: the "keep secrets server-side" rule from the API-integration lesson is exactly this rule. When a value must stay private, the browser calls your server, and your server — reading a real, non-VITE_ env var — does the sensitive work. The BFF pattern exists largely to make this clean.

.env, .gitignore & .env.example

The .env file holds real values, some of them secret, so it must never enter version control. But teammates still need to know which variables to set — so you commit a sanitized template instead.

// .gitignore — keep every real env file out of Git.
.env
.env.local
.env.*.local

// .env.example — COMMITTED. Keys with blank or placeholder values,
// so a new teammate copies it to .env and fills in the blanks.
NODE_ENV=development
PORT=3001
DATABASE_URL=mongodb://localhost:27017/myapp
JWT_SECRET=            # generate your own
CORS_ORIGINS=http://localhost:5173

Practice & Quiz

require('dotenv').config();
// TODO: validate required vars, then export the parsed config object.
module.exports = {
  // port: ...,  debug: ...,  databaseUrl: ...,  jwtSecret: ...
};

require('dotenv').config();

const required = ['DATABASE_URL', 'JWT_SECRET'];
const missing = required.filter((k) => !process.env[k]);
if (missing.length > 0) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

module.exports = {
  port: parseInt(process.env.PORT, 10) || 3001,
  debug: process.env.DEBUG === 'true',
  databaseUrl: process.env.DATABASE_URL,
  jwtSecret: process.env.JWT_SECRET
};

Best Practices & Pitfalls

✅ Do

• Call dotenv.config() (or use --env-file) at the very top of your entry file
• Funnel all config through one validated config module
• Parse types explicitly: parseInt for numbers, === 'true' for booleans
• Commit a .env.example template; add .env to .gitignore
• Keep real secrets server-side; only public values get a VITE_ prefix

❌ Don't

• Commit a real .env — and if you ever do, rotate the secret, don't just delete it
• Treat any frontend variable as private; the bundle is public
• Read process.env in dozens of files; centralize it
• console.log(process.env) — it dumps every secret into your logs
• Assume env values are typed; they are always strings

Summary

📚 Additional Resources

• The Twelve-Factor App — Config
• Vite — Env Variables and Modes
• dotenv — npm package
• Node.js — process.env

🚀 What's Next?

You've connected frontend to backend with CORS, structured the calls with clean integration patterns, and configured both sides safely. Next the connection goes live and two-way: WebSocket Fundamentals — persistent, real-time channels for chat, notifications, and live dashboards.