Environment variables are a core concept in modern web development. Whether you are building a simple Node.js app, a React project, or a full-stack application, you will eventually work with files like .env and .env.local.
Many beginners get confused about the difference between these two files. Why do we need both? When should we use .env and when should we use .env.local? Are they the same or different?
In this guide, we will break everything down in simple terms so you can understand how these files work, why they are important, and how to use them properly in real projects.
What Are Environment Variables?
Environment variables are key-value pairs used to store configuration data outside your main application code. Instead of hardcoding sensitive information like API keys, database passwords, or secret tokens inside your code, you store them in environment variables.
For example:
DB_HOST=localhost DB_USER=root DB_PASSWORD=secret123 API_KEY=abcd1234
This makes your application more secure and flexible.
What Is a .env File?
The .env file is the main file used to store environment variables for your application. It is usually located in the root directory of your project.
This file contains default configuration values that are used across environments.
Example of .env
APP_NAME=MyApp API_URL=https://api.example.com DB_HOST=localhost DB_PORT=3306
The .env file is often shared across the team (except sensitive data in production).
What Is .env.local?
The .env.local file is used for local development. It allows developers to override values from the .env file without affecting others.
This file is typically not committed to version control and is listed in .gitignore.
Example of .env.local
DB_PASSWORD=my_local_password API_KEY=my_local_api_key
This ensures your personal or sensitive data remains private.
Key Difference Between .env and .env.local
| Feature | .env | .env.local |
|---|---|---|
| Purpose | Default configuration | Local overrides |
| Version Control | Sometimes committed | Never committed |
| Usage | Shared config | Personal config |
| Priority | Lower priority | Higher priority |
How .env and .env.local Work Together
When your application starts, it loads environment variables in a specific order. If a variable exists in both .env and .env.local, the value from .env.local will override the .env value.
This allows developers to keep common settings in .env while customizing local values in .env.local.
Why You Should Not Store Secrets in .env
Many beginners make the mistake of committing sensitive data inside the .env file. If this file is pushed to GitHub, your API keys and passwords can be exposed.
That is why .env.local is preferred for sensitive local data.
Use Cases
Using .env
- App name
- Public API URLs
- Default configuration
Using .env.local
- Database passwords
- Private API keys
- Local testing credentials
Framework Behavior (Next.js Example)
In frameworks like Next.js, the loading order is:
- .env.local
- .env.development
- .env
This means .env.local has the highest priority.
Best Practices
- Always add .env.local to .gitignore
- Never expose secrets in public repos
- Use different env files for different environments
- Keep .env clean and minimal
Common Mistakes
- Committing .env.local to Git
- Hardcoding secrets in code
- Not using environment variables properly
Conclusion
Understanding the difference between .env and .env.local is essential for modern development. These files help you manage configurations, improve security, and keep your application flexible.
Use .env for shared configuration and .env.local for personal or sensitive data. Following this approach will make your development workflow cleaner and more secure.
💡 Quick Tip:
Never commit your .env.local file to GitHub.
It usually contains sensitive data like API keys, database credentials, or tokens — and once it’s public, it’s very hard to recover.
👉 Always add .env.local to .gitignore
Have you ever accidentally exposed environment variables in a project? 😅