Environment Variables in Node.js with dotenv

DATABASE_URL=postgres://localhost:5432/myapp — the line that, when accidentally committed to a public repo, costs companies millions in breached data. Environment variables are the most basic infrastructure decision in any Node.js application, yet teams consistently get them wrong: committing .env files, lacking validation, using the same config for development and production. This article covers the correct setup, validation patterns, production secrets management, and the one pattern that prevents the most common environment variable disaster.

Why Environment Variables Matter in Production

Hardcoding configuration values like database passwords, API keys, or secret tokens directly into your source code is a security risk and a maintenance nightmare. In production, you need to separate configuration from code to allow different settings across environments without modifying the codebase. Environment variables provide a standard way to inject configuration into your Node.js application at runtime. They keep secrets out of version control, enable per-environment overrides, and simplify deployment pipelines. The Twelve-Factor App methodology explicitly recommends storing config in environment variables. Without them, you risk exposing credentials in Git history, breaking deployments due to config mismatches, or accidentally shipping debug settings to production. This article walks you through using the dotenv package to manage environment variables safely and effectively.

# .env.example
# Copy this file to .env and fill in your values
DB_HOST=localhost
DB_PORT=5432
DB_USER=myapp
DB_PASS=changeme
API_KEY=your-api-key-here
NODE_ENV=development

Setting Up dotenv in Your Project

The dotenv package loads environment variables from a .env file into process.env. Install it as a production dependency: npm install dotenv. Then, at the very top of your application's entry point (e.g., app.js or index.js), add require('dotenv').config(). This reads the .env file and merges its key-value pairs into process.env. If you're using ES modules, use import 'dotenv/config' instead. The .env file should never be committed to version control; instead, provide a .env.example file with dummy values. For local development, each developer creates their own .env file. In production, you typically set environment variables through your hosting platform (e.g., Heroku config vars, AWS ECS environment, Docker compose) and skip the .env file entirely. This setup ensures your code works identically across all environments.

// app.js
require('dotenv').config();

const express = require('express');
const app = express();

const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send(`Hello from ${process.env.NODE_ENV || 'development'}`);
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

The .env File Format and Best Practices

The .env file uses a simple KEY=VALUE format. Each line defines one variable. Values can be quoted (single or double) if they contain spaces or special characters. Comments start with #. There's no need to export variables; dotenv handles that. Best practices: use uppercase with underscores for variable names (e.g., DB_HOST). Group related variables with comments. Never store sensitive values in .env.example. Use default values in code when a variable might be missing (e.g., const port = process.env.PORT || 3000). For boolean values, use strings like 'true' and 'false' and parse them explicitly. Avoid using .env in production; instead, set variables via the OS or container orchestration. If you must use a file in production, ensure it's outside the application root and has restricted permissions (e.g., chmod 600).

# Database configuration
DB_HOST=prod-db.example.com
DB_PORT=5432
DB_USER=app_user
DB_PASS=s3cret!Pass

# Feature flags
ENABLE_CACHE=true
LOG_LEVEL=info

# Third-party keys
STRIPE_API_KEY=sk_live_...

Accessing Environment Variables in Code

After loading dotenv, you access variables via process.env.VARIABLE_NAME. This returns a string (or undefined if not set). Always validate required variables at startup. For example, if your app needs a database URL, check if it exists and crash early with a clear error message. Use defaults for optional variables. For numbers, parse them explicitly (e.g., parseInt(process.env.PORT, 10)). For booleans, compare the string value (e.g., process.env.DEBUG === 'true'). Never trust that a variable is set; always handle missing values gracefully. In production, you might want to use a validation library like joi or env-var to enforce types and required fields. This prevents runtime errors due to misconfiguration.

// config.js
require('dotenv').config();

const required = ['DB_HOST', 'DB_USER', 'DB_PASS', 'API_KEY'];
const missing = required.filter(key => !process.env[key]);
if (missing.length) {
  throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
}

module.exports = {
  db: {
    host: process.env.DB_HOST,
    port: parseInt(process.env.DB_PORT, 10) || 5432,
    user: process.env.DB_USER,
    password: process.env.DB_PASS,
  },
  apiKey: process.env.API_KEY,
  isProduction: process.env.NODE_ENV === 'production',
};

Managing Multiple Environments (Development, Staging, Production)

Different environments need different configurations. The simplest approach is to have separate .env files per environment, e.g., .env.development, .env.staging, .env.production. Then load the appropriate one based on NODE_ENV. You can use dotenv.config({ path: .env.${process.env.NODE_ENV} }). However, in production, you should not use .env files at all; set variables via the platform. For local development, you can have a .env file that overrides defaults. Another pattern is to use a single .env file with all variables, but override specific ones with environment-specific files. The key is consistency: your code should read from process.env regardless of how the variables were set. Use a configuration module that centralizes all environment variable access, making it easy to see what's expected.

// config.js
const dotenv = require('dotenv');
const path = require('path');

const env = process.env.NODE_ENV || 'development';

// Load environment-specific .env file if it exists
const envFile = path.resolve(__dirname, `../.env.${env}`);
dotenv.config({ path: envFile });

// Also load .env for local overrides (optional)
dotenv.config();

module.exports = {
  nodeEnv: env,
  port: process.env.PORT || 3000,
  dbUrl: process.env.DATABASE_URL,
};

Security: Keeping Secrets Out of Source Control

The primary reason to use environment variables is security. Never commit secrets to Git. Add .env to .gitignore immediately. Use .env.example as a template with placeholder values. For teams, consider using a secrets manager like HashiCorp Vault, AWS Secrets Manager, or Doppler. These tools inject secrets at runtime, avoiding files altogether. If you must use files, encrypt them (e.g., with git-crypt or sops). Also, be careful with logging: never log environment variables directly. A common production incident is accidentally printing process.env in a debug log, exposing secrets in log aggregation tools. Use a sanitized logger that redacts sensitive fields. Finally, rotate secrets regularly and audit who has access.

# .gitignore
.env
.env.*
!env.example

Testing with Environment Variables

Testing code that relies on environment variables can be tricky because process.env is global. You have a few options: (1) Set variables in your test runner's setup (e.g., Jest's setupFiles). (2) Use a library like dotenv with a test-specific .env.test file. (3) Mock process.env using a utility like jest.resetModules() to reload modules with different env values. The cleanest approach is to inject configuration via a config module that can be mocked. For example, instead of reading process.env.DB_HOST directly in your database module, read it from a config object that you can replace in tests. This makes your code testable without side effects. Always reset environment variables between tests to avoid leakage.

// __tests__/config.test.js

describe('config', () => {
  const OLD_ENV = process.env;

  beforeEach(() => {
    jest.resetModules();
    process.env = { ...OLD_ENV };
  });

  afterAll(() => {
    process.env = OLD_ENV;
  });

  test('should use default port when PORT is not set', () => {
    delete process.env.PORT;
    const config = require('../config');
    expect(config.port).toBe(3000);
  });

  test('should read PORT from environment', () => {
    process.env.PORT = '4000';
    const config = require('../config');
    expect(config.port).toBe(4000);
  });
});

Common Pitfalls and How to Avoid Them

Several mistakes plague developers new to dotenv. (1) Forgetting to call dotenv.config() before accessing variables. (2) Committing the .env file. (3) Using .env in production. (4) Assuming variables are always set. (5) Not parsing types (e.g., treating 'false' as truthy). (6) Overwriting existing environment variables (dotenv does not overwrite by default, but you can force it with { override: true }). (7) Loading dotenv in multiple places, causing confusion. (8) Using spaces around = in .env file (they become part of the key or value). (9) Expecting dotenv to expand variables. (10) Not handling missing .env file gracefully (dotenv doesn't throw if the file is missing, but you might want to warn). Avoid these by following the practices outlined in this article: load early, validate, type-check, and never commit secrets.

// BAD: Loading dotenv too late
const db = require('./db'); // reads process.env.DB_HOST before dotenv loaded
require('dotenv').config();

// BAD: Not parsing boolean
if (process.env.DEBUG) { // always true if set to 'false'
  console.log('debug mode');
}

// BAD: Using .env in production
if (process.env.NODE_ENV === 'production') {
  require('dotenv').config(); // don't do this
}

Alternatives to dotenv and When to Use Them

While dotenv is great for local development, production environments often need more robust solutions. (1) Platform-native variables: Heroku, AWS ECS, Docker Compose, and Kubernetes all support setting environment variables natively. (2) Secrets managers: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, and GCP Secret Manager provide encrypted storage and rotation. (3) Configuration services: Consul, etcd, or Spring Cloud Config for distributed systems. (4) Encrypted files: Use sops or git-crypt to encrypt .env files in the repo. (5) Environment variable validators: Libraries like env-var or joi enforce types and required fields. For most Node.js apps, start with dotenv for development and switch to platform variables for production. If you need to manage secrets across many services, invest in a secrets manager. The principle remains: separate config from code.

// using env-var for validation
const env = require('env-var');

const config = {
  port: env.get('PORT').default(3000).asPortNumber(),
  dbHost: env.get('DB_HOST').required().asString(),
  debug: env.get('DEBUG').default('false').asBoolStrict(),
};

module.exports = config;

Putting It All Together: A Production-Ready Setup

Here's a complete, production-ready pattern. Your entry point loads dotenv only if not in production. A config module validates and exports typed variables. The rest of the app imports config, not process.env directly. This centralizes configuration, makes testing easy, and prevents scattered process.env calls. In production, you set variables via the platform (e.g., Docker environment, Kubernetes secrets). The .env file is never committed. Use .env.example as documentation. Add a startup check that crashes the app if required variables are missing. This pattern has served us well across dozens of Node.js services, from small APIs to microservices handling millions of requests.

// index.js - entry point
if (process.env.NODE_ENV !== 'production') {
  require('dotenv').config();
}

const config = require('./config');
const app = require('./app');

app.listen(config.port, () => {
  console.log(`Server running in ${config.nodeEnv} on port ${config.port}`);
});

// config.js
const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter(key => !process.env[key]);
if (missing.length) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

module.exports = {
  nodeEnv: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT, 10) || 3000,
  databaseUrl: process.env.DATABASE_URL,
  apiKey: process.env.API_KEY,
  isProduction: process.env.NODE_ENV === 'production',
};

Node 20+ Built-in --env-file CLI Flag

Starting with Node 20, you can load environment variables from a file without any third-party library. The --env-file flag allows you to specify a path to a .env file when running your application. This is a zero-dependency solution for simple use cases. For example, node --env-file=.env server.js loads variables from .env into process.env. This approach is ideal for small projects or scripts where you want to avoid adding dotenv. However, it lacks features like variable expansion, override, or multi-file support. For production, you may still prefer dotenv for its flexibility and ecosystem. Note that --env-file is still experimental in Node 20, so use with caution in critical environments.

# Run your app with .env file
node --env-file=.env server.js

process.loadEnvFile() and util.parseEnv()

Node 20 also introduces process.loadEnvFile() as a programmatic alternative to the CLI flag. This method loads a .env file into process.env at runtime. For example, process.loadEnvFile('.env') does the same as dotenv.config(). Additionally, util.parseEnv() parses a string of key-value pairs into an object, useful for custom parsing. These built-ins reduce dependency on dotenv for basic loading. However, they don't support variable expansion, override, or multi-file loading. If your project needs those features, stick with dotenv. The built-ins are best for minimal setups or when you want to avoid third-party code in a security-critical context.

import { parseEnv } from 'node:util';

// Load .env file
process.loadEnvFile('.env');

// Parse a custom string
const env = parseEnv('KEY=VALUE\nFOO=BAR');
console.log(env); // { KEY: 'VALUE', FOO: 'BAR' }

dotenv-expand for Variable Expansion

Variable expansion allows you to reference other environment variables within your .env file using ${VAR} syntax. For example, DATABASE_URL=${HOST}:${PORT}/db. The dotenv-expand package adds this capability to dotenv. Install it with npm install dotenv-expand, then use dotenvExpand.expand(dotenv.config()). This is essential for reducing duplication and centralizing configuration. Without expansion, you'd have to hardcode values or use string concatenation in code. Note that expansion order matters: variables are expanded in the order they appear in the file. Use it wisely to avoid circular references. For production, always validate that expanded variables resolve correctly.

import dotenv from 'dotenv';
import dotenvExpand from 'dotenv-expand';

const myEnv = dotenv.config();
dotenvExpand.expand(myEnv);

console.log(process.env.DATABASE_URL);

DOTENV_CONFIG_ Env Config and Override Option

dotenv supports configuration via environment variables prefixed with DOTENV_CONFIG_. For example, DOTENV_CONFIG_PATH sets the path to the .env file, and DOTENV_CONFIG_DEBUG enables debug logging. This is useful for CI/CD pipelines or Docker containers where you want to override the default behavior without code changes. Additionally, dotenv's override option (available since v16) allows you to overwrite existing process.env values. By default, dotenv does not override existing variables. Set { override: true } in dotenv.config() to force overwrite. This is critical when you need to ensure that environment variables from a file take precedence over system-set ones, or vice versa. Use with caution to avoid accidental overwrites.

import dotenv from 'dotenv';

// Override existing env vars
dotenv.config({ override: true });

// Or use DOTENV_CONFIG_ env vars
// DOTENV_CONFIG_PATH=/custom/path/.env node app.js

Multi-File Loading Patterns

In complex projects, you may need to load multiple .env files, such as .env for defaults, .env.local for local overrides, and .env.production for production-specific values. dotenv supports this by calling dotenv.config() multiple times. The order matters: later calls override earlier ones. A common pattern is to load .env first, then .env.local (if it exists), and finally .env.${NODE_ENV}. This allows you to have a base configuration that can be overridden per environment. Use the path option to specify each file. For security, ensure that .env.local is in .gitignore. This pattern is widely used in frameworks like Next.js and is production-proven.

import dotenv from 'dotenv';
import { existsSync } from 'fs';

// Load base .env
dotenv.config({ path: '.env' });

// Load local overrides if exists
if (existsSync('.env.local')) {
  dotenv.config({ path: '.env.local', override: true });
}

// Load environment-specific file
const envFile = `.env.${process.env.NODE_ENV || 'development'}`;
if (existsSync(envFile)) {
  dotenv.config({ path: envFile, override: true });
}