Manage a .env Environment File

Environment files are the standard mechanism for injecting configuration and secrets into applications without hardcoding them in source code. The .env file format, popularized by the dotenv library and now supported natively by Node.js, Docker, Docker Compose, and most cloud platforms, stores key-value pairs that are loaded into the process environment at startup. Getting .env file management right is a foundational security and operational practice. This example shows a typical Node.js application's .env file with ten variables covering the most common categories: runtime mode (NODE_ENV), server configuration (PORT), database connection (DATABASE_URL with connection string format), caching (REDIS_URL), security (JWT_SECRET), third-party API access (API_KEY), email delivery (SMTP_* variables), and frontend configuration (NEXT_PUBLIC_API_URL). The most important rule for .env files: never commit them to version control. Add .env to your .gitignore immediately when starting a project, before the first commit. The standard practice is to commit a .env.example file that contains all the variable names with placeholder values but no real secrets. New team members clone the repo, copy .env.example to .env, and fill in the real values from a secure secrets store or team password manager. The NEXT_PUBLIC_ prefix convention demonstrates framework-specific env variable handling: Next.js only exposes variables prefixed NEXT_PUBLIC_ to the browser-side JavaScript bundle. Variables without this prefix are available only in server-side code. Vite uses VITE_ as its prefix. Create React App used REACT_APP_. Always check your framework's documentation to understand which variables are sent to the client, because client-side environment variables are visible in the browser's source code. Layers of .env files: modern frameworks support multiple .env files that merge in a defined priority order. .env is the base file for all environments. .env.local overrides for local development only and is never committed. .env.production contains production-specific values and may or may not be committed (without secrets). The exact loading behavior varies by framework — check the documentation for your specific stack. Common .env pitfalls: whitespace around the equals sign (KEY = VALUE vs KEY=VALUE) is interpreted differently by different parsers — use no spaces. Values containing special characters like $, #, or spaces should be quoted with double quotes. Duplicate variable names cause unpredictable behavior (which one wins depends on the parser) — the env file editor highlights duplicates so you can clean them up. Tips: for production deployments, inject secrets via the deployment platform's secret management (Heroku Config Vars, AWS Secrets Manager, Kubernetes Secrets) rather than deploying a .env file to the server. This provides audit trails, access control, and automatic rotation capabilities.

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-secret-key-here
API_KEY=sk-example-key-12345
SMTP_HOST=smtp.example.com
SMTP_PORT=587
[email protected]
NEXT_PUBLIC_API_URL=https://api.example.com