Environment Variables and Secrets Management in Node.js

Why Environment Variables Matter

Environment variables separate configuration from code, allowing the same application code to run in development, staging, and production with different databases, API keys, and settings. They also keep secrets out of version control — a database password committed to a public GitHub repository is an immediate security incident. Every Node.js application should use environment variables for all configuration that changes between environments.

Using dotenv

The dotenv package loads variables from a .env file into process.env. Install dotenv and call dotenv.config() at the very start of your application entry point. Create a .env file with KEY=value pairs. Add .env to your .gitignore to prevent committing secrets. Commit a .env.example file with the same keys but no values as documentation for other developers.

Validating Environment Variables at Startup

Validate that all required environment variables are present when the application starts. Use Zod to define a schema for your env vars and parse process.env against it. If validation fails, throw an error and exit — a startup failure is much better than a runtime error 30 minutes into operation because a required API key is missing. Typed env validation also gives you autocomplete for process.env across your codebase.

Environment-Specific Configuration

Create separate .env files for different environments: .env.development, .env.test, .env.production. Load the appropriate file based on process.env.NODE_ENV. In tests, use .env.test with a test database URI so tests never affect development data. Never commit any .env file that contains real credentials — only commit .env.example files with empty or example values.

Secrets Managers for Production

For production applications, use a dedicated secrets manager rather than .env files: AWS Secrets Manager, Google Cloud Secret Manager, HashiCorp Vault, or Doppler. Secrets managers provide: versioning, audit logs of who accessed which secret, automatic rotation, and fine-grained access control. Your application fetches secrets at startup from the secrets manager rather than from environment variables set by deployment scripts.

Rotating Secrets and Emergency Procedures

Rotate secrets regularly and immediately after any suspected compromise. When a secret is rotated, update it in the secrets manager and redeploy your application. For critical secrets (database passwords, API keys with billing access), set up alerting when they are accessed from unexpected IP addresses or at unusual times. Document your secret rotation procedure so it can be executed quickly under pressure during a security incident.