Managing Environment Variables in Node.js: The Complete Guide

# .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

Enter fullscreen mode Exit fullscreen mode

// 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' });
}

Enter fullscreen mode Exit fullscreen mode

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)

Enter fullscreen mode Exit fullscreen mode

Best Practices

.gitignore

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

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

Enter fullscreen mode Exit fullscreen mode

.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

Enter fullscreen mode Exit fullscreen mode

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! 🎉

Enter fullscreen mode Exit fullscreen mode

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"]

Enter fullscreen mode Exit fullscreen mode

# 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:

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

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.