.env.development.local

What is .env.development.local and why it matters

.env.development.local is a dotenv-style environment file commonly used in JavaScript/Node and frontend projects (Create React App, Vite, Next.js, etc.) to store development-only environment variables that should override other development settings on a single machine. It fits into a conventional dotenv hierarchy where different files target different environments and scopes (e.g., .env, .env.development, .env.production, .env.local).

Create React App (CRA)

CRA has native support for this pattern. When you run npm start, it automatically loads:

  • .env
  • .env.development
  • .env.local
  • .env.development.local (highest priority) All variables must be prefixed with REACT_APP_.

5. Security and .gitignore

The most important rule regarding .env.development.local is ignoring it. .env.development.local

When you initialize a project, you should ensure your .gitignore file includes the following lines:

# .gitignore
# Local env files
.env.local
.env.development.local
.env.test.local
.env.production.local

Why? If you commit this file, you defeat the purpose of the .local suffix. You risk exposing secrets (API keys, database passwords) on GitHub/GitLab, and you force your local configuration onto your teammates. What is

3. Do Not Use in Production Servers

The .local suffix implies a physical developer machine. Never upload .env.development.local to a cloud VM, Docker container, or PaaS like Heroku or Vercel. Use the platform's native environment variable configuration panel instead.

The Naming Breakdown

  • .env: The standard file for default values.
  • .development: Specifies that these variables apply only when the application is running in "development" mode (e.g., running npm start).
  • .local: The most critical part. This indicates that the file is for local overrides and should not be committed to the repository.

Next.js

Next.js has a built-in loader for .env files. they work fine

  • Supported: Yes.
  • Special behavior: Next.js blurs the line between server and browser. Variables are inlined at build time.
  • Caution: In Next.js, .env.development.local is loaded during next dev. However, to expose a variable to the browser, you still need the NEXT_PUBLIC_ prefix.
  • Best practice: Use .env.development.local for local API keys that should never reach version control.

When to use it

  • You need a per-developer override during development that should never be committed.
  • You want to keep team-wide development defaults in .env.development but allow individuals to customize without editing that file.
  • You run services locally with credentials that must not be shared (local API tokens, database passwords).

"Is this a Windows problem?"

File names starting with a dot (.) are hidden on Unix/Mac. On Windows, they work fine, but Git Bash or PowerShell may hide them by default. Use ls -Force or dir /a.