How-To Guide

How to Set Up .env Files

Complete configuration guide for local development

TL;DR

TL;DR: Create a .env.local file in your project root with KEY=value pairs. Add it to .gitignore . Most modern frameworks (Next.js, Vite) load .env files automatically. For Node.js, install the dotenv package and import it at the top of your entry file.

File Naming Conventions

File	Purpose	Commit to Git?
.env	Base defaults	Sometimes (no secrets)
.env.local	Local overrides with secrets	Never
.env.development	Development environment	Sometimes
.env.production	Production environment	Never
.env.example	Template with placeholder values	Yes

Step-by-Step Setup

Create your .env.local file

In your project root, create .env.local:

# .env.local

# Database
DATABASE_URL=postgresql://localhost:5432/mydb

# API Keys
STRIPE_SECRET_KEY=sk_test_xxxxx
OPENAI_API_KEY=sk-xxxxx

# Public variables (exposed to browser in Next.js)
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Add to .gitignore

Make sure .env files with secrets are never committed:

# .gitignore

# Environment files
.env
.env.local
.env.*.local
.env.production

# Keep the example
!.env.example

Create an example file

Create .env.example as a template for other developers:

# .env.example - Copy to .env.local and fill in values

DATABASE_URL=postgresql://user:password@localhost:5432/dbname
STRIPE_SECRET_KEY=sk_test_your_key_here
OPENAI_API_KEY=sk-your_key_here
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co

Framework-Specific Setup

Next.js

Next.js loads .env files automatically. No installation needed.

// Access in server components, API routes, etc.
const apiKey = process.env.STRIPE_SECRET_KEY;

// Access in client components (must have NEXT_PUBLIC_ prefix)
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

Vite (React, Vue, Svelte)

Vite also loads .env files automatically, but uses a different prefix:

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

// Access in code
const apiUrl = import.meta.env.VITE_API_URL;

Node.js (Express, etc.)

For plain Node.js, install the dotenv package:

npm install dotenv

Then import it at the very top of your entry file:

// index.js or server.js - MUST be first import
import 'dotenv/config';
// or: require('dotenv').config();

// Now process.env has your variables
const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;

Create React App

CRA uses the REACT_APP_ prefix:

# .env.local
REACT_APP_API_URL=https://api.example.com

// Access in code
const apiUrl = process.env.REACT_APP_API_URL;

.env File Syntax

# Comments start with #
# Basic format: KEY=value (no spaces around =)

# Simple values
PORT=3000
NODE_ENV=development

# Strings with spaces need quotes
APP_NAME="My Awesome App"

# URLs don't need quotes
API_URL=https://api.example.com/v1

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

# Reference other variables (in some implementations)
BASE_URL=https://api.example.com
FULL_URL=${BASE_URL}/v1

Common Syntax Mistakes

Spaces around =: KEY = value (wrong)
Trailing spaces: KEY=value (can cause issues)
Missing quotes with spaces: NAME=My App (wrong)

Loading Order

Most frameworks load .env files in this order (later files override earlier ones):

.env
.env.local
.env.development or .env.production (based on NODE_ENV)
.env.development.local or .env.production.local

Pro tip: Use .env.local for local secrets and .env for shared, non-sensitive defaults.

Do I need to restart my dev server after changing .env?

Yes. Environment variables are loaded when your application starts. After changing .env.local, restart your dev server with npm run dev or equivalent.

Why isn't my variable showing up?

Check: 1) You restarted the dev server, 2) The variable is in .env.local not just .env, 3) For browser access, you're using the correct prefix (NEXT_PUBLIC_, VITE_, REACT_APP_).

Should I commit .env files?

Never commit files with real secrets. You can commit .env with non-sensitive defaults or .env.example as a template. Always keep .env.local and any file with secrets in .gitignore.

How to Set Up .env Files - Complete Guide