Example .env.example :
# .env.development (shared) DEBUG_LEVEL=info USE_MOCK_PAYMENT_GATEWAY=true But on your local machine, you need to trace a deep bug:
# .env.development.local (local only) DEBUG_LEVEL=trace USE_MOCK_PAYMENT_GATEWAY=false Because .local files have priority, the settings in .env.development.local override the shared ones. 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. The Danger Zone: What NOT to Put in .env.development.local While this file is powerful, it is also a common source of security leaks. Because the file is local , it is easy to assume it is safe. However, the greatest risk is accidental commits . .env.development.local
In the modern landscape of software development—particularly within the JavaScript/Node.js and React/Vue ecosystems—environment variables are the bedrock of secure, configurable applications. They allow us to keep API keys, endpoint URLs, and feature flags separate from our source code.
However, as applications grow in complexity, a single .env file often isn't enough. Developers need distinct configurations for development, testing, staging, and production. This is where the specific, nuanced file naming convention——comes into play. Example
const dotenv = require('dotenv'); const path = require('path'); // Load base .env dotenv.config({ path: path.resolve(process.cwd(), '.env') });
# Create a file named .env.development.local and add: DATABASE_URL=postgres://user:pass@localhost:5432/mydb STRIPE_SECRET_KEY=pk_test_your_local_key_here 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. 4. Use Framework-Specific Prefixes Remember that CRA (React) requires REACT_APP_ , Vite requires VITE_ , and Next.js exposes all by default. Using the wrong prefix is the #1 reason environment variables appear undefined . Conclusion: The Silent Hero of Local Development The humble file .env.development.local is easily overlooked, but mastering it transforms a chaotic development setup into a smooth, personalized experience. It respects the delicate balance between shared team configuration and individual developer freedom. Instead of modifying the shared file (and risking
API_URL=https://default.api.com APP_TITLE=My App