Next Js Env File Highest Priority List

Next.js loads environment variables from files in a specific order, where files higher in the list override variables found in files lower in the list.

Here is the environment variable loading order from Highest Priority (used first) to Lowest Priority (default/fallback):

🥇 Highest Priority (The Overrides)

1. .env.{NODE_ENV}.local

   • Examples:
     • When running next dev (NODE_ENV=development): .env.development.local
     • When running next build or next start on production (NODE_ENV=production): .env.production.local
   • Purpose: These files contain machine-specific secrets for a given environment and should be included in your .gitignore file.

2. .env.local

   • Loaded In: All environments except test.
   • Purpose: Local overrides that apply to all environments on your development machine (e.g., forcing a production API URL during local development, as you asked previously). This file should also be included in .gitignore.

🥈 Medium Priority (Environment-Specific)

3. .env.{NODE_ENV}
   • Examples:
     • When running next dev: .env.development
     • When running next build or next start: .env.production
   • Purpose: Environment-specific configurations (non-secrets) that can be safely committed to source control (Git).

🥉 Lowest Priority (The Defaults)

4. .env
   • Loaded In: All environments.
   • Purpose: General, cross-environment default values and fallbacks.

---

Summary Table

| File Name | Priority | NODE_ENV=development (next dev) | NODE_ENV=production (next build) | Notes | | :--- | :--- | :--- | :--- | :--- | | .env.development.local / .env.production.local | 1 (Highest) | .env.development.local | .env.production.local | Local, secret, environment-specific overrides. | | .env.local | 2 | .env.local | .env.local | Local overrides for all environments. | | .env.development / .env.production | 3 | .env.development | .env.production | Non-secret, environment-specific configurations. | | .env | 4 (Lowest) | .env | .env | General defaults/fallbacks. |

Key Takeaway: If a variable like API_URL is defined in both .env.development.local and .env.development, Next.js will use the value from .env.development.local.