Contact the Turkey iResidence Application Center to help you get started
Master .env.development.local: The Modern Developer's Guide Managing configuration settings is a core part of building modern web applications. Whether you're using React, Next.js, or Node.js, the .env.development.local file is an essential tool for keeping your local development environment secure and flexible. What is .env.development.local?
In modern development frameworks, environment variables are often split into multiple files to handle different stages of a project's lifecycle. .env.development.local is a specialized file designed to hold local-only configuration for your development environment.
Unlike standard .env files, this specific file is intended to be ignored by version control (Git). This makes it the perfect place to store: Personal API keys (e.g., OpenAI or AWS credentials). Local database passwords. Feature flags you want to toggle only on your machine. Machine-specific paths or ports. The Order of Operations: How Overrides Work
Most tools, like Create React App and Next.js, load environment files in a specific priority. Typically, .env.development.local has the highest priority during local development. The common lookup order is: .env.development.local (Highest priority, unversioned) .env.local .env.development (Versioned, shared dev settings) .env (Lowest priority, default settings) Best Practices for Security .env and .env.local | by Naman Ahuja | Medium
.env FileWhen you start a new project (using Create React App, Vite, or dotenv in Node.js), the first thing you usually do is create a .env file in the root directory. This file works. But it has two major flaws:
.env to Git (it belongs in .gitignore). But if it isn't committed, new developers have to manually create it. If it is committed, you risk leaking secrets.postgres://prod-db but your Local database URL is postgres://localhost? You can't keep both in one file without commenting/uncommenting constantly.To solve this, framework authors invented file hierarchy and mode-specific files.
.env.development.local: A Deep Dive into Environment-Specific ConfigurationIn 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—.env.development.local—comes into play.
This article is a deep exploration of what .env.development.local is, why it exists, how it interacts with other .env files, and crucially, how to use it without accidentally leaking sensitive data to your production environment or version control system.
If you aren't using a frontend framework, you can replicate this behavior with the dotenv-flow package.
require('dotenv-flow').config();
It automatically respects the NODE_ENV variable and loads .env.development.local when NODE_ENV=development.
.env.development.local acts as your personal "scratchpad" for environment variables during the development phase. It allows you to:
By adhering to the .gitignore standards and prefix rules of your specific framework, you can utilize this file to streamline your personal workflow while keeping the shared codebase clean.
Title: ".env.development.local: A Best Practice for Environment-Specific Configuration in Software Development"
Abstract:
In software development, managing environment-specific configuration is crucial for ensuring the smooth operation of applications across different environments, such as development, testing, staging, and production. One popular approach to achieve this is by using environment files, specifically .env.development.local. This paper explores the concept of .env.development.local, its benefits, and best practices for using it in software development.
Introduction:
Environment-specific configuration is a common challenge in software development. Different environments require distinct settings, such as database connections, API keys, and server configurations. Hardcoding these settings directly into the application code can lead to errors, security vulnerabilities, and difficulties in maintaining and scaling the application. To address this issue, developers often use environment files, which store configuration settings specific to each environment.
.env.development.local is a widely adopted convention for environment files. The .env prefix indicates that the file contains environment variables, while .development specifies the environment type, and .local denotes that the file is intended for local development only. This file contains key-value pairs of configuration settings, which are loaded into the application's environment variables.
Benefits of .env.development.local:
.env.development.local allows developers to keep environment-specific configuration separate from the application code, making it easier to manage and maintain..env.development.local facilitates collaboration among team members by providing a standardized way to configure the development environment.Best Practices:
.env.[environment].[machine], to ensure clarity and organization..env.secrets.local, to add an extra layer of security..env file template (without sensitive information) to version control, but exclude environment-specific files (e.g., .env.development.local) to prevent exposure of sensitive data.dotenv or envsubst to automate the loading of environment variables from .env.development.local into the application.Conclusion:
.env.development.local has become a widely accepted best practice for environment-specific configuration in software development. By adopting this approach, developers can ensure a clear separation of concerns, improve security, and facilitate collaboration. By following best practices, such as consistent naming conventions, separating sensitive information, and automating environment configuration, developers can maximize the benefits of using .env.development.local.
References:
Appendix:
Example of a .env.development.local file:
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=myuser
DB_PASSWORD=mypassword
API_KEY= myapikey
Example of a dotenv configuration file:
require('dotenv').config(
path: './.env.development.local',
);
The .env.development.local file is a powerful feature used in modern web development frameworks like Next.js, Create React App, and Vue CLI. It allows developers to define local, environment-specific overrides that are never shared with other team members or committed to version control. Core Features
Highest Priority Overrides: In development mode, variables defined in .env.development.local take precedence over those in .env, .env.local, and .env.development.
Git-Ignored by Default: Standard templates automatically include this file in .gitignore to prevent sensitive credentials (like personal API keys or local database passwords) from leaking into the repository.
Context-Specific: It is only loaded when the environment variable NODE_ENV is set to development. Comparison of File Priorities
When running in development mode, frameworks typically load files in this order (where the last file loaded or highest listed overrides previous ones): .env (Default values for all environments) .env.local (Local overrides for all environments) .env.development (Values specific to development)
.env.development.local (Your personal local overrides for development) Implementation Example
If you are working on a feature that requires a different API endpoint than the rest of your team, you can specify it locally:
# .env.development.local # This overrides the REACT_APP_API_URL defined in .env.development REACT_APP_API_URL=http://localhost:4000/my-custom-feature MY_PRIVATE_KEY=your_secret_key_here Use code with caution. Copied to clipboard Usage Tips Adding Custom Environment Variables | Create React App
.env.development.local file is a specialized configuration file used in modern web development frameworks like Create React App
. It is used to store sensitive or machine-specific environment variables that should only be active during local development. Core Purpose Local Overrides
: Its primary role is to override default development settings without affecting other team members' environments. Development Only
: Variables in this file are only loaded when the application is running in "development" mode (e.g., npm run dev Security & Privacy : It is intended to be kept local to your machine and must never be committed to version control (Git). Loading Priority (Hierarchy)
Frameworks typically load environment files in a specific order of precedence. In most systems like .env.development.local highest priority for development environments: .env.development.local (Highest priority; local machine overrides) .env.local (Local overrides for all modes except .env.development (Shared development settings) (Default settings for all environments) Best Practices
How can I handle dev and testing environment on a single machine? .env.development.local
In modern web development frameworks like Next.js and Vite, the .env.development.local file is a specialized environment configuration file used to store personal settings and secrets specifically for the development stage of a project. Core Purpose and Priority
This file acts as the ultimate override for development-specific variables. When you run your application in development mode (typically via npm run dev or yarn start), the system looks for variables across several files. In frameworks like Next.js, .env.development.local holds the highest priority. The typical hierarchy (from highest to lowest priority) is:
.env.development.local (Specific to you and the development mode)
.env.development (Specific to the development mode, shared with the team) .env.local (Personal overrides for all modes except test) .env (Default values shared across all environments) Key Characteristics
Local and Private: This file is intended for your machine only. It should never be committed to version control (like Git). You should always ensure it is listed in your .gitignore file.
Security: It is the ideal place to store sensitive information like personal API keys, database passwords, or auth tokens that you use during development but don't want others on your team to see or use.
Mode-Specific: Unlike .env.local, which might load in both development and production build modes, .env.development.local is strictly for when the application is running in "development" mode. Common Use Cases
Personal Database Credentials: Connecting to a local database instance that has a different username or password than the one used by other developers.
Feature Toggles: Enabling a specific experimental feature on your machine without affecting the rest of the team.
Third-Party API Keys: Using your own personal sandbox key for services like Stripe or AWS to avoid hitting team rate limits. Best Practices ENV variables in Rails 7.x - rubyonrails-talk
The Last Local Environment
Maya stared at the blinking cursor in her terminal. The deadline was seventeen hours away, and the staging environment had just collapsed like a house of cards in a hurricane.
"Again," she muttered.
She had three backup environments. The cloud one was throttled. The CI one was broken by someone’s rushed merge. And the production one — she wasn’t even allowed to think about production.
But there was a fourth.
She navigated to the project root and typed ls -a. There it was, hidden in plain sight:
.env.development.local
She hadn't touched it in months. It was considered dirty — local-only, never committed, full of experimental keys and mock services. A file with no dignity. The technical equivalent of a sticky note on a server rack.
But right now, it was the only thing that worked.
She opened it.
# Emergency local overrides - do not share
API_GATEWAY=http://localhost:8999
MOCK_PAYMENTS=true
FORCE_LEGACY_FALLBACK=1
DEVELOPMENT_MODE_OVERRIDE=ok
She almost laughed. This wasn’t an environment file. It was a confession. Every line was a past mistake, a late-night hack, a promise to fix this later.
But later was now.
She uncommented a line she’d added two years ago:
SECRET_SAUCE_ENABLED=true
Nothing happened.
Then—slowly—the local services started waking up. The mock payments fired. The legacy fallback routed around the dead staging servers. And somewhere in the chaos, her feature began to work.
Maya sat back. The file sat there, quietly doing its job. No CI pipeline. No code review. No cloud. Just her, her laptop, and a .local file that everyone else had forgotten.
She made a mental note: Refactor this mess tomorrow.
But she knew. Tomorrow, she’d still have that file. And she’d quietly love it.
Because sometimes the ugliest solution is the one that saves you at 3 a.m.
And sometimes, .env.development.local is the truest environment of all.
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.
Create .vscode/extensions.json:
"recommendations": ["mikestead.dotenv"]
Then in .vscode/settings.json:
"files.associations":
".env.development.local": "dotenv"
,
"[dotenv]":
"editor.tokenColorCustomizations": [
"scope": "variable.other.env",
"settings":
"foreground": "#9CDCFE"
]
Your backend database runs on port 5432 on the main server, but on your specific laptop, you changed it to 5433 due to a conflict.
If you are using dotenv manually, you can implement this pattern yourself using the dotenv-expand package or by conditionally loading files:
const dotenv = require('dotenv'); const path = require('path');// Load base .env dotenv.config( path: path.resolve(process.cwd(), '.env') );
// Load environment-specific if (process.env.NODE_ENV === 'development') dotenv.config( path: path.resolve(process.cwd(), '.env.development') );
// Load local override (highest priority) dotenv.config( path: path.resolve(process.cwd(), '.env.development.local') );