Chapter 8 — Environment Variables & Configuration

The why

The 12-factor principle "store config in the environment" exists because the same binary must run in dev, staging, and prod with different secrets. Hardcoded config = leaked secrets and risky deploys.

What goes where

Rule of thumb: if it differs across environments, it's config. If a security review would flag it, it's a secret.

dotenv

.env is a flat file at the project root:

DATABASE_URL=postgresql://postgres:secret@localhost:5432/app
JWT_SECRET=dev-secret-do-not-use-in-prod
LOG_LEVEL=debug
PORT=3000

Load it once at the top of your entry file:

import 'dotenv/config';
// rest of imports...

That populates process.env. Never commit .env. Add it to .gitignore immediately:

.env
.env.*.local

Commit a .env.example with empty / placeholder values so teammates know what to set.

Validate at boot

This is the one trick most apps skip. Validate env vars when the app starts. If something's missing, crash before serving the first request — not at 3am when one specific code path runs.

import { z } from 'zod';
 
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'test', 'production']),
  PORT: z

Now anywhere in the app:

import { config } from './config';
const port = config.PORT;  // typed as number

Three wins: typed, validated, no process.env.X strewn through the codebase.

Layering for dev / staging / prod

Three places config can come from:

1. .env — local dev defaults.
2. CI / cloud secret manager — injected at deploy time.
3. Code defaults — last resort.

Order: runtime env > .env > code defaults. dotenv won't overwrite already-set values, so production envs always win.

For environment-specific behavior:

if (config.NODE_ENV === 'production') {
  // turn on stricter cookie settings, etc.
}

Avoid scattering if (env === ...) everywhere. Instead, branch once in config:

export const config = {
  ...result.data,
  cookies: result.data.NODE_ENV === 'production'
    ? { secure: true, sameSite: 'strict' as const }
    : { secure:

Secret managers — what you graduate to

.env is fine for dev. Production secrets should live in:

• AWS Secrets Manager / SSM Parameter Store
• HashiCorp Vault
• GCP Secret Manager
• Doppler / Infisical / 1Password
• GitHub Actions / your CI's secret store (injects at deploy)

The pattern is identical: the app reads process.env.X; the platform sets X from the secret store. Your code doesn't care.

Rotation

Secrets must be rotatable. Hardcoded secrets are not. Test that you can rotate a secret without downtime:

1. Add the new secret (JWT_SECRET_NEW).
2. Verify against either old or new.
3. Switch signing to new.
4. After all tokens expire, remove old.

We'll cover this in L3.

Common mistakes

Production · Performance · Security notes

Production. Print which env vars are loaded at startup (names only, never values). Helps diagnose "why is this env different from that env."

Security. Never log env vars. Never put them in error messages. Never serialize the config object into a response.

Exercises

1. Beginner. Add .env.example listing required vars.
2. Beginner. Write a config.ts that validates with Zod.
3. Intermediate. Crash the app deliberately by removing a required var. Verify the error is helpful.
4. Advanced. Rotate the JWT_SECRET without downtime — sign with the new, verify with either.

Summary

Config in the environment, validated once at boot, accessed through a typed config object. .env for dev, secret manager for prod. Never commit .env. Layer your config so prod overrides dev overrides defaults.

Quick recall

• Config in env, code in code.
• Validate at boot with Zod.
• .env in .gitignore, .env.example checked in.
• Different secrets per environment.

Quiz

1. What's the worst thing about committing .env to git?
2. Why validate env vars at boot rather than at usage?
3. Where should production secrets live?
4. What's the order of precedence for env vars?