Environment Variables: Config Outside Your Code

Why it exists

Hardcoding configuration like API keys into your source code is brittle and insecure. It makes it difficult to deploy the same code to different environments (dev, staging, production) and risks exposing secrets in your version control history. The Twelve-Factor App methodology solves this by storing configuration in the environment, completely separate from the code.

The mental model

An environment variable is a key-value pair provided by the operating system to a running process. For local development, a .env file acts as a convenient simulator for this environment. A library like dotenv reads this file and injects its contents into your Node.js application's process.env object, making the variables accessible just as if the OS had set them. It's a local stand-in for how production servers manage configuration.

How it works

First, you create a .env file in your project's root directory with KEY=VALUE pairs, one per line. For example, DATABASE_URL="postgres://user:pass@host:port/db". Then, you install the dotenv package. As early as possible in your application's entry file (like index.js), you add the line require('dotenv').config(). This single line reads the .env file, parses it, and attaches all the key-value pairs to the global process.env object. Your code can then access process.env.DATABASE_URL anywhere.

When to use it

Use environment variables for any value that changes between deployments or contains sensitive information. This includes API keys, database credentials, port numbers, domain names, or feature flags. The goal is to have one codebase that can run in any environment without modification, just by changing the environment variables.

When not to use it

Do not use environment variables for configuration that is fixed and doesn't change between environments, like a list of supported timezones or a static algorithm parameter. This type of configuration belongs in a regular JSON or JS config file that is committed to your repository. Also, .env files are primarily for development; in production, you should use your hosting provider's mechanism for setting environment variables (e.g., Heroku Config Vars, AWS Secrets Manager, Docker environment flags).

One canonical example

A web server needs to connect to a database and an external API. The .env file would look like this: PORT=3000, DATABASE_URL="postgres://...", OPENAI_API_KEY="sk-...". Your index.js starts with require('dotenv').config(). Then, your server setup code uses const port = process.env.PORT || 8080; and your database client uses process.env.DATABASE_URL to connect. This setup works locally, and when deployed, the production environment provides its own values for these variables without any code changes. Crucially, your .gitignore file must contain a line with .env to prevent committing secrets.