Environment Variables 101: A Developer's Complete Guide

If you have ever seen a .env file in a project or typed process.env.DATABASE_URL in your code, you have worked with environment variables. But many developers use them without fully understanding what they are, why they exist, or how to manage them properly. This guide covers everything from the basics to production best practices.

What Are Environment Variables?

Environment variables are key-value pairs that exist outside your application code. They are part of the operating system's environment and can be read by any process running in that environment.

# Setting an environment variable (Linux/macOS)
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

# Reading it in Node.js
const dbUrl = process.env.DATABASE_URL;

# Reading it in Python
import os
db_url = os.environ["DATABASE_URL"]

The key insight is separation of configuration from code. Your application code stays the same whether it is running on your laptop, in a staging server, or in production. Only the environment variables change.

Why Environment Variables Matter

1. Security

Hardcoding secrets in source code is one of the most common security mistakes. If your code contains const stripeKey = "sk_live_abc123", that secret is now in your git history forever, visible to anyone who can clone the repository.

Environment variables keep secrets out of your codebase entirely. The code only references the variable name, never the value.

2. Portability

A single application can connect to different databases, use different API keys, and behave differently across environments, all without changing a single line of code. Deploy the same Docker image everywhere and let environment variables handle the differences.

3. Twelve-Factor App Compliance

The twelve-factor app methodology, a widely adopted set of best practices for building modern web applications, lists "store config in the environment" as its third factor. Environment variables are the standard way to achieve this.

The .env File

Typing export DATABASE_URL=... for every variable every time you open a terminal is tedious. That is where .env files come in.

A .env file is a simple text file containing key-value pairs:

# .env
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
STRIPE_SECRET_KEY=sk_test_abc123
JWT_SECRET=my-super-secret-key
APP_ENV=development
DEBUG=true

Libraries like dotenv (Node.js), python-dotenv (Python), and godotenv (Go) automatically load these files into your application's environment at startup.

Managing Multiple Environments

Most applications need at least three environments: development, staging, and production. Each needs different configuration values.

The common approach is multiple .env files:

.env                 # Local development (default)
.env.staging         # Staging environment
.env.production      # Production environment
.env.example         # Template with dummy values (committed to git)

Only .env.example should be committed to your repository. It serves as documentation for what variables the application needs, without containing real values.

Common Mistakes

Mistake 1: Committing .env to Git

Your .gitignore should always include:

.env
.env.local
.env.staging
.env.production
.env*.local

Mistake 2: No Validation at Startup

If your app needs DATABASE_URL and it is missing, you want to know immediately, not when the first database query fails ten minutes later. Validate required environment variables at startup.

Mistake 3: Using the Same Secrets Everywhere

Your development database password should not be the same as your production database password. If a developer's laptop is compromised, production should not be affected.

Mistake 4: No Rotation Strategy

API keys and passwords should be rotated regularly. If you do not have a system for updating secrets across all environments, rotation becomes so painful that it never happens.

Best Practices

Beyond .env Files

For solo developers, .env files work fine. But the moment you add a second team member, problems emerge. How do you share the .env file securely? How do you keep everyone in sync when a value changes? How do you revoke access when someone leaves?

This is where a tool like ConfigShield comes in. Import your .env file once, and your entire team can pull secrets via CLI. Every access is encrypted, logged, and revocable. It is the .env workflow developers already know, but with the security and collaboration features a team needs.