Environment Variables: The Complete Guide to Managing Config Safely

What Are Environment Variables?

Environment variables are key-value pairs stored in the operating system's environment, outside your application code. They let you configure an application differently across environments (development, staging, production) without changing the code.

DATABASE_URL=postgresql://localhost:5432/mydb
SECRET_KEY=abc123
NODE_ENV=production
PORT=3000

The key rule: secrets and config should never be hardcoded in source code. Environment variables are how you keep them out.

---

The .env File

For local development, the .env file is the standard way to set environment variables. The dotenv library loads it automatically.

# .env
DATABASE_URL=postgresql://localhost:5432/devdb
SECRET_KEY=dev-secret-not-real
STRIPE_SECRET_KEY=sk_test_your_stripe_key_here
PORT=3000
NODE_ENV=development

Node.js with dotenv:

npm install dotenv

// At the very top of your entry file
import "dotenv/config";
// or
require("dotenv").config();

const dbUrl = process.env.DATABASE_URL;

Node.js 20.6+ has built-in .env support — no package needed:

node --env-file=.env server.js

---

CRITICAL: Add .env to .gitignore

Never commit .env to version control. This is the most common way secrets get leaked.

# .gitignore
.env
.env.local
.env.production

Instead, commit a .env.example file with placeholder values:

# .env.example — safe to commit
DATABASE_URL=postgresql://localhost:5432/yourdb
SECRET_KEY=your-secret-key-here
STRIPE_SECRET_KEY=sk_test_your-key
PORT=3000
NODE_ENV=development

This documents what variables are needed without exposing real values.

---

Naming Conventions

Use SCREAMING_SNAKE_CASE. Be descriptive:

# Good
DATABASE_URL=...
STRIPE_SECRET_KEY=...
SENDGRID_API_KEY=...
NEXT_PUBLIC_SITE_URL=...   # NEXT_PUBLIC_ prefix = exposed to browser in Next.js

# Bad
DB=...
KEY=...
SECRET=...

Group related variables with a prefix:

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=myapp

REDIS_HOST=localhost
REDIS_PORT=6379

---

Validation at Startup

Never let your app start with missing required variables. Catch it immediately:

// env.js — validate on startup
const required = [
  "DATABASE_URL",
  "SECRET_KEY",
  "STRIPE_SECRET_KEY",
];

for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}

export const env = {
  databaseUrl: process.env.DATABASE_URL,
  secretKey: process.env.SECRET_KEY,
  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
  port: parseInt(process.env.PORT || "3000", 10),
  nodeEnv: process.env.NODE_ENV || "development",
};

For more robust validation, use zod:

npm install zod

import { z } from "zod";

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  SECRET_KEY: z.string().min(32),
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(["development", "staging", "production"]).default("development"),
});

export const env = envSchema.parse(process.env);

If any variable is missing or invalid, your app crashes on startup with a clear error — far better than a cryptic runtime failure hours later.

---

Environment Variables in CI/CD

Never put secrets in your docker-compose.yml, Dockerfile, or CI config files.

GitHub Actions:

# .github/workflows/deploy.yml
steps:
  - name: Deploy
    env:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
    run: npm run deploy

Add secrets under Repository Settings → Secrets and Variables → Actions.

Docker:

# Pass at runtime, not in Dockerfile
docker run -e DATABASE_URL=postgresql://... myapp

# Or use --env-file
docker run --env-file .env.production myapp

Never do this:

# WRONG — baked into the image layer, visible in docker history
ENV DATABASE_URL=postgresql://real-host/prod

---

Multiple Environments

Use separate .env files per environment:

.env.development    # local dev
.env.test           # test runner
.env.staging        # staging server
.env.production     # production (NEVER commit this)

Load the right one based on NODE_ENV:

dotenv -e .env.${NODE_ENV} node server.js

Or in Next.js — it handles this automatically: .env.local overrides .env.

---

Secrets Management at Scale

For production applications, a .env file on a server is a security risk. Use a secrets manager instead:

• AWS Secrets Manager — retrieve secrets programmatically
• HashiCorp Vault — enterprise secrets management
• Doppler — developer-friendly secrets manager, syncs to any platform
• Vercel / Netlify / Railway — built-in environment variable management

Example with Doppler:

doppler run -- node server.js
# Doppler injects env vars at runtime — no .env file needed on the server

---

Security Checklist

• .env is in .gitignore
• .env.example is committed with placeholder values
• All required variables are validated at startup
• Secrets are not logged (especially in error handlers)
• Different secrets per environment (dev secrets ≠ prod secrets)
• Rotate secrets if they're ever exposed
• Use a secrets manager in production

---

Conclusion

Environment variables are the simplest and most universal way to configure applications. The rules are straightforward: never hardcode secrets, never commit .env, always validate on startup, and use a proper secrets manager for production. Following these practices prevents the most common class of security incidents — accidentally exposed credentials.