Managing Environment Variables in Node.js: The Complete Guide

Stop hardcoding secrets. Here's how to do it right.

The Problem

// ❌ NEVER do this
const DB_PASSWORD = 'SuperSecret123!';
const API_KEY = 'sk-live-abc123def456';
const STRIPE_SECRET = 'sk_test_...';

Solution 1: .env Files (The Standard)

# .env file (NEVER commit this!)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=admin
DB_PASSWORD=secret123
API_URL=https://api.example.com
API_KEY=abc123
NODE_ENV=development
PORT=3000

// Load .env (at the very top of your app, before anything else)
import 'dotenv/config';
// or: require('dotenv').config();

// Access variables
const dbHost = process.env.DB_HOST;
const port = process.env.PORT || 3000;

Solution 2: Validation with Zod

// config.js — Validate all env vars at startup
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  JWT_SECRET: z.string().min(32),
  REDIS_URL: z.string().optional(),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

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

// If any required variable is missing or invalid → crashes at startup!
// This is GOOD — fail fast instead of failing randomly during runtime.

Solution 3: Multi-Environment Config

# .env.development (local dev)
DATABASE_URL=postgres://localhost:5432/myapp_dev
API_KEY=dev_key_123
LOG_LEVEL=debug

# .env.production (production)
DATABASE_URL=postgres://prod-db:5432/myapp_prod
API_KEY=prod_key_456
LOG_LEVEL=info

# .env.test (testing)
DATABASE_URL=:memory:
API_KEY=test_key_789
LOG_LEVEL=error

// Load the right .env file based on NODE_ENV
import dotenv from 'dotenv';
import path from 'path';

dotenv.config({
  path: path.resolve(
    process.cwd(),
    `.env.${process.env.NODE_ENV || 'development'}`
  ),
});

// Fallback to default .env
if (!process.env.DATABASE_URL) {
  dotenv.config({ path: '.env' });
}

Solution 12-Factor App Principles

1. Code and config are separate
2. Config is in environment variables
3. Different environments have different configs
4. Secrets are never in code or version control
5. All config is externalized (no hardcoded values)

Best Practices

.gitignore

# Never commit these files!
.env
.env.local
.env.*.local
*.env

# But DO commit templates:
# .env.example ✅

.env.example Template

# Copy this file to .env and fill in your values
# cp .env.example .env

# Server
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# API
API_KEY=your_api_key_here
API_SECRET=your_api_secret_here

# Auth
JWT_SECRET=generate_a_random_string_at_least_32_chars
JWT_EXPIRES_IN=7d

# External services
STRIPE_SECRET_KEY=sk_test_xxx
SENDGRID_API_KEY=SG.xxxx
REDIS_URL=redis://localhost:6379

Type Safety for Env Vars

// types/env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    readonly NODE_ENV: 'development' | 'production' | 'test';
    readonly PORT: string;
    readonly DATABASE_URL: string;
    readonly API_KEY: string;
    readonly JWT_SECRET: string;
    // Optional vars
    readonly REDIS_URL?: string;
    readonly LOG_LEVEL?: 'debug' | 'info' | 'warn' | 'error';
  }
}

// Now TypeScript will autocomplete and type-check your env vars!
process.env.DATABASE_URL; // string
process.env.JWT_SECRET;   // string
process.env.UNKNOWN_VAR;  // TypeScript error! 🎉

Docker + Environment Variables

# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 3000
CMD ["node", "dist/index.js"]

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "${PORT:-3000}:3000"
    environment:
      - NODE_ENV=${NODE_ENV:-production}
      - DATABASE_URL=${DATABASE_URL}
      - API_KEY=${API_KEY}
      - JWT_SECRET=${JWT_SECRET}
    env_file:
      - .env.production
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

CI/CD Environment Variables

# GitHub Actions (.github/workflows/ci.yml)
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test
        env:
          # Set via GitHub repo Settings → Secrets → Actions
          DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}
          API_KEY: ${{ secrets.TEST_API_KEY }}
          JWT_SECRET: test-secret-for-ci-only

Security Checklist

• [ ] No secrets in source code (including git history!)
• [ ] .env files in .gitignore
• [ ] .env.example committed (template without real values)
• [ ] Secrets stored in vault/secrets manager (not .env in production)
• [ ] Different keys per environment (dev ≠ prod)
• [ ] Keys rotated regularly
• [ ] Access logs for sensitive operations
• [ ] No console.log of secrets (even in development)
• [ ] Git pre-commit hook that scans for secrets
• [ ] git-secrets or detect-secrets tool installed

Quick Reference

Tool	Use Case
dotenv	Load .env files
zod	Validate env vars
envalid	Alternative validator
config	Node.js built-in config
cross-env	Set env vars cross-platform
dotenv-cli	Run commands with .env loaded
vault	HashiCorp secret management
AWS SM	AWS Parameter Store / Secrets Manager

---

How do you manage environment variables? Any tools I missed?

Follow @armorbreak for more backend content.