What “create .env.local (do not commit)” really means

What “create .env.local (do not commit)” really means

If you’ve seen instructions like “create .env.local (do not commit)” in docs for frameworks like Next.js, React, or Node.js, here’s the clear, no-fluff breakdown of what to do, why it matters, and how to avoid leaking secrets.

---

What is .env.local?

• Local-only config: A file for environment variables that apply only on your machine (API keys, database URLs, toggles).
• Overrides: Values in .env.local typically override .env when running locally.
• Format: One KEY=VALUE per line, no quotes needed unless values contain spaces.

API_KEY=12345abcdef

DATABASE_URL=postgres://user:pass@localhost:5432/mydb

FEATURE_FLAG=true

---

Why “do not commit”?

• Secrets: It often contains sensitive info (API keys, passwords) that should never be public.
• Machine-specific: Your local paths or ports won’t match teammates or servers.
• Security hygiene: Keeping secrets out of git prevents accidental leaks and audit headaches.

---

How to safely ignore .env.local in Git

Add it to your .gitignore (create this file in your repo root if it doesn’t exist):

# Environment files (local-only)

.env.local

.env.*.local

Already committed it by accident? Remove it from git history now:

git rm --cached .env.local

git commit -m "Stop tracking .env.local"

git push

---

Share structure without secrets

Use an example file so teammates know what variables to create:

# .env.example (commit this one)

API_KEY=

DATABASE_URL=

FEATURE_FLAG=

Teammates copy it:

cp .env.example .env.local

# then fill in actual values locally

---

Common setups and loading behavior

• Next.js: Loads .env.local automatically for development. Client-side exposed vars must be prefixed with NEXT_PUBLIC_.
• Create React App: Uses .env.local with REACT_APP_ prefix for variables exposed to the browser.
• Node.js apps: Often use dotenv to load env files. Production usually uses real environment variables, not files.

// Node.js example (dotenv)

import dotenv from "dotenv";

dotenv.config({ path: ".env.local" });

console.log(process.env.API_KEY);

---

Production vs. local

• Local: .env.local lives only on developer machines.
• Production: Prefer secure environment variables via your platform (Vercel, Netlify, Docker, Kubernetes, CI/CD, or server configuration).
• No secrets in repo: Never store real API keys in committed files—even private repos can leak.

---

Pitfalls to avoid

• Forgetting .gitignore: If it’s not ignored, it can be committed accidentally.
• Wrong prefixes: Browser-visible vars need framework-specific prefixes (e.g., NEXT_PUBLIC_, REACT_APP_).
• Mixing environments: Don’t reuse local values in production; use platform-managed secrets.
• Stale cache: Restart dev server after changing env files; some frameworks read them only at startup.

---

Quick checklist

• Create: Make .env.local with your local secrets.
• Ignore: Add it to .gitignore.
• Document: Commit a .env.example with placeholders.
• Load: Ensure your framework reads it (or configure dotenv).
• Separate: Use platform env vars in staging/production.

---

TL;DR

“Create .env.local (do not commit)” means: Make a local env file for your machine, put secrets/configs there, and keep it out of Git to protect sensitive data and avoid machine-specific conflicts.