Your team’s .env.development points to a shared staging database. You, however, are testing a new migration script and need to point to localhost:5432/my_local_db. Instead of modifying the shared file (and risking committing the change), you add DATABASE_URL=postgres://localhost/my_local_db to .env.development.local. When you switch to production mode, this file is completely ignored.
There is a common pitfall: forgetting that .env.development.local exists.
Scenario: You add API_URL=https://production-api.com to .env.development.local for a one-time test. A week later, you are debugging why your local app is hitting production. You forgot you left the override in place.
Solution: rm .env.development.local or use git status to see untracked files regularly. .env.development.local
To understand .env.development.local, you must first understand the naming syntax used by almost every major build tool (Webpack, Vite, Next.js, dotenv-flow). Your team’s
The pattern looks like this:
.env.[mode].[local] When you switch to production mode, this file
Let's break down each component: