When you run npm run build --mode=production , the system loads .env.production , then overwrites it with .env.local.production . If your application must work in an offline environment (e.g., an IoT device, a ship, or a secure government facility), you might prepopulate caches, mock external APIs, or use local fallbacks. These settings should only be active when NODE_ENV=production and you are on a specific approved machine.
Therefore, if your NODE_ENV was set to production , the framework would look for .env.production.local . .env.local.production
# .env.local.production (not in Git) DATABASE_URL="postgresql://localhost:5432/prod_mirror" STRIPE_SECRET_KEY="sk_test_localDebugKey" NEXT_PUBLIC_ANALYTICS_ID="debug-123" This file allows you to simulate a production environment without touching real production secrets. Sometimes, the process of building your application (minification, bundling, tree-shaking) requires specific flags. For example, you might enable source maps only in local production builds, but not in real production. When you run npm run build --mode=production ,
# Real production (on the server) GENERATE_SOURCEMAP=false LOG_LEVEL=error GENERATE_SOURCEMAP=true # Override to debug bundled code LOG_LEVEL=debug # See everything during local build Therefore, if your NODE_ENV was set to production
Here are three scenarios where .env.local.production (or its equivalent) is indispensable. The most common reason. You are about to deploy to AWS, Vercel, or Netlify. Your staging environment works flawlessly, but production fails mysteriously.
The difference is purely syntactical. Most modern frameworks prefer the former ( env.production.local ), but legacy systems or custom CI/CD pipelines might recognize the latter. If you have .env and .env.production , why introduce a third file? The answer lies in sensitive, environment-specific configuration .
At first glance, it looks like a typo. Is it local? Is it production? Why would you need both? If you’ve stumbled upon this file or are considering implementing it, this guide is for you.