Environment Variables and Secrets Management

Proper secrets management prevents data breaches. This guide covers handling configuration and sensitive data securely.

Environment Variables Basics#

Loading Environment Variables#

// .env file (never commit!)
DATABASE_URL=postgresql://user:pass@localhost:5432/db
API_KEY=sk_live_abc123
NODE_ENV=development

// Load with dotenv
import 'dotenv/config';

// Or manually
import dotenv from 'dotenv';
dotenv.config({ path: '.env.local' });

// Access variables
const dbUrl = process.env.DATABASE_URL;

Type-Safe Environment Variables#

// env.ts
import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  PORT: z.coerce.number().default(3000),
  ENABLE_LOGGING: z.coerce.boolean().default(true),
});

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

// Usage - fully typed!
console.log(env.PORT); // number
console.log(env.NODE_ENV); // 'development' | 'production' | 'test'

Next.js Environment Variables#

# .env.local (gitignored)
DATABASE_URL=postgresql://...
SECRET_KEY=abc123

# .env (can be committed)
NEXT_PUBLIC_API_URL=https://api.example.com

# Access
# Server-side: process.env.DATABASE_URL
# Client-side: process.env.NEXT_PUBLIC_API_URL (NEXT_PUBLIC_ prefix required)

Secrets Managers#

AWS Secrets Manager#

import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const client = new SecretsManager({ region: 'us-east-1' });

async function getSecret(secretName: string): Promise<Record<string, string>> {
  const response = await client.getSecretValue({ SecretId: secretName });

  if (response.SecretString) {
    return JSON.parse(response.SecretString);
  }

  throw new Error('Secret not found');
}

// Usage
const dbCredentials = await getSecret('prod/database');
const connectionString = `postgresql://${dbCredentials.username}:${dbCredentials.password}@${dbCredentials.host}:5432/mydb`;

HashiCorp Vault#

import Vault from 'node-vault';

const vault = Vault({
  endpoint: process.env.VAULT_ADDR,
  token: process.env.VAULT_TOKEN,
});

async function getSecret(path: string) {
  const { data } = await vault.read(`secret/data/${path}`);
  return data.data;
}

// Usage
const apiKeys = await getSecret('api-keys');
console.log(apiKeys.stripe_key);

Google Secret Manager#

import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const client = new SecretManagerServiceClient();

async function getSecret(name: string): Promise<string> {
  const [version] = await client.accessSecretVersion({
    name: `projects/my-project/secrets/${name}/versions/latest`,
  });

  return version.payload?.data?.toString() || '';
}

CI/CD Secrets#

GitHub Actions#

# .github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          API_KEY: ${{ secrets.API_KEY }}
        run: |
          npm run deploy

Environment-Specific Secrets#

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Links to GitHub environment
    steps:
      - name: Deploy
        env:
          # Secrets from 'production' environment
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        run: npm run deploy

Docker Secrets#

Docker Compose#

# docker-compose.yml
services:
  app:
    image: myapp
    secrets:
      - db_password
      - api_key
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    external: true  # Created via `docker secret create`

Reading Secret Files#

import fs from 'fs';

function getDockerSecret(name: string): string {
  const secretPath = `/run/secrets/${name}`;

  if (fs.existsSync(secretPath)) {
    return fs.readFileSync(secretPath, 'utf8').trim();
  }

  // Fallback to environment variable
  return process.env[name.toUpperCase()] || '';
}

const dbPassword = getDockerSecret('db_password');

Kubernetes Secrets#

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DATABASE_URL: postgresql://user:pass@host:5432/db
  API_KEY: sk_live_abc123

---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: app
          envFrom:
            - secretRef:
                name: app-secrets

Best Practices#

Never Commit Secrets#

# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
secrets/

Use Different Secrets Per Environment#

# Development
.env.development

# Staging
.env.staging

# Production
.env.production  # Or use secrets manager

Rotate Secrets Regularly#

// Support multiple API keys during rotation
const API_KEYS = [
  process.env.API_KEY_NEW,
  process.env.API_KEY_OLD,
].filter(Boolean);

function validateApiKey(key: string): boolean {
  return API_KEYS.includes(key);
}

Audit Secret Access#

async function getSecret(name: string, reason: string) {
  logger.info({
    action: 'secret_access',
    secretName: name,
    reason,
    timestamp: new Date().toISOString(),
  });

  return secretsManager.getSecret(name);
}

What NOT to Do#

// ❌ Never hardcode secrets
const API_KEY = 'sk_live_abc123';

// ❌ Never log secrets
console.log('API Key:', process.env.API_KEY);

// ❌ Never expose in error messages
throw new Error(`Failed with key: ${apiKey}`);

// ❌ Never commit .env files
// ❌ Never store in client-side code

Use environment variables for configuration, secrets managers for production secrets, and never commit sensitive data. Implement type-safe validation, rotate credentials regularly, and audit access to sensitive data.