Managing .env and Environment Variables in Node.js

Introduction to Environment Variables

Environment variables are key-value pairs that configure your application's behavior without hardcoding values in your source code. They're essential for managing secrets, API keys, and environment-specific configuration. This guide covers best practices for using .env files and environment variables in Node.js applications.

Why Use Environment Variables?

Security

• Keep secrets out of source code
• Never commit API keys to Git
• Different credentials per environment

Flexibility

• Same code in dev, staging, production
• Easy configuration changes without deployment
• Container and cloud-native deployment

The .env File

Basic Syntax

# .env file
# Comments start with #

DATABASE_URL=postgres://user:pass@localhost:5432/mydb
API_KEY=sk-abc123def456
PORT=3000
DEBUG=true
NODE_ENV=development

# Strings with spaces need quotes
APP_NAME="My Application"

# Multi-line values
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

File Naming Conventions

.env                 # Default, loaded in all environments
.env.local           # Local overrides (git-ignored)
.env.development     # Development-specific
.env.production      # Production-specific
.env.test            # Test-specific
.env.example         # Template for required variables

Using dotenv in Node.js

Installation

npm install dotenv

Basic Usage

// Load at the top of your entry file
import 'dotenv/config';
// or
require('dotenv').config();

// Access variables
const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY;

Conditional Loading

import dotenv from 'dotenv';

// Load different files based on NODE_ENV
const envFile = `.env.${process.env.NODE_ENV || 'development'}`;
dotenv.config({ path: envFile });

// Override with local file
dotenv.config({ path: '.env.local', override: true });

Type Safety with TypeScript

Type Definitions

// types/env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: 'development' | 'production' | 'test';
    PORT: string;
    DATABASE_URL: string;
    API_KEY: string;
  }
}

Validation with Zod

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']),
  PORT: z.string().transform(Number),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
});

// Validate and parse
const env = envSchema.parse(process.env);

// Use typed env
console.log(env.PORT); // number
console.log(env.DATABASE_URL); // string

Framework Integration

Next.js

// .env.local (automatically loaded)
DATABASE_URL=postgres://...

// Public variables (exposed to browser)
NEXT_PUBLIC_API_URL=https://api.example.com

// Usage in code
const apiUrl = process.env.NEXT_PUBLIC_API_URL;  // Client-safe
const dbUrl = process.env.DATABASE_URL;           // Server-only

Vite

// .env
VITE_API_URL=https://api.example.com

// Usage (only VITE_ prefixed vars are exposed)
const apiUrl = import.meta.env.VITE_API_URL;

Express

// config.js
import 'dotenv/config';

export const config = {
  port: parseInt(process.env.PORT) || 3000,
  dbUrl: process.env.DATABASE_URL,
  isProduction: process.env.NODE_ENV === 'production',
  logLevel: process.env.LOG_LEVEL || 'info',
};

// app.js
import { config } from './config.js';
app.listen(config.port);

Security Best Practices

.gitignore

# Always ignore .env files with secrets
.env
.env.local
.env.*.local

# Keep example file
!.env.example

.env.example Template

# .env.example (commit this to repo)
# Copy to .env and fill in values

DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your-api-key-here
PORT=3000
NODE_ENV=development

Secret Rotation

// Support multiple API keys during rotation
const apiKeys = process.env.API_KEYS?.split(',') || [];

function validateApiKey(key) {
  return apiKeys.includes(key);
}

Production Deployment

Docker

# Dockerfile - don't include .env
FROM node:20
COPY . .
RUN npm install
CMD ["node", "server.js"]

# docker-compose.yml
services:
  app:
    build: .
    env_file:
      - .env.production
    environment:
      - NODE_ENV=production

Cloud Platforms

# Vercel
vercel env add DATABASE_URL production

# Heroku
heroku config:set DATABASE_URL=postgres://...

# AWS (via Parameter Store or Secrets Manager)
aws ssm put-parameter --name "/app/DATABASE_URL" --value "..." --type SecureString

Common Patterns

Default Values

const port = process.env.PORT || 3000;
const host = process.env.HOST ?? 'localhost';
const debug = process.env.DEBUG === 'true';

Required Variables

function requireEnv(name) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

const apiKey = requireEnv('API_KEY');

Parsing Complex Values

# .env
ALLOWED_ORIGINS=http://localhost:3000,https://example.com
FEATURE_FLAGS={"darkMode":true,"betaFeatures":false}

// JavaScript
const origins = process.env.ALLOWED_ORIGINS?.split(',') || [];
const features = JSON.parse(process.env.FEATURE_FLAGS || '{}');

Tools and Resources

For working with configuration:

• JSON Formatter - Format JSON config values
• Base64 Encoder - Encode binary secrets
• Hash Generator - Generate secure tokens

Troubleshooting

Variables Not Loading

// Check if dotenv is loaded first
console.log(process.env.MY_VAR); // undefined

// Solution: import dotenv before other imports
import 'dotenv/config';
import { myModule } from './module.js';

Different Values in Production

// Debug: log which file is loaded
console.log('NODE_ENV:', process.env.NODE_ENV);
console.log('Loading from:', `.env.${process.env.NODE_ENV}`);

Conclusion

Environment variables are essential for secure, flexible applications. Key takeaways:

• Never commit secrets to source control
• Use .env files for local development
• Validate environment variables at startup
• Use platform-specific secret management in production
• Keep .env.example updated for team onboarding

For more developer resources, explore our free online tools. For dotenv documentation, see dotenv on GitHub.