Then he wrote a new rule in the team handbook, in bold red text:
In modern JavaScript applications (Next.js, Vite, Create React App), environment variables are managed via .env files. While .env , .env.local , .env.production , and .env.development are common, .env.local.production sits at a specific intersection: .
Here is a production-grade template for managing your env files.
file was meant for the build server, not for a local machine. But Alex didn't want to change the team's shared file and risk breaking everyone else's local setup. The Discovery of the Secret Scroll Alex consulted the ancient Next.js Documentation and discovered a hidden gem: the .env.local.production file (sometimes used as .env.production.local depending on the framework's priority rules). This file was a ghost—it was listed in the .gitignore .env.local.production
If your production build relies on specific analytics keys, production databases, or stricter OAuth redirect URIs, you can place those credentials inside .env.local.production . This ensures your local production test behaves exactly like the live site without polluting your standard .env.development workflow. 2. Guarding Third-Party API Rate Limits and Billing
# .env.example NEXT_PUBLIC_APP_URL=https://your-app-url.com API_KEY=your-api-key-here DATABASE_URL=your-database-url-here
This hierarchy is applied differently depending on the command you run. For npm start (development), the load order is: .env.development.local > .env.local > .env.development > .env . For npm run build (production), the order is: .env.production.local > .env.local > .env.production > .env . Then he wrote a new rule in the
The key takeaways are:
contains environment-specific settings for the development environment. This file can be committed to version control as it should not contain secrets.
GitHub Actions or GitLab CI often run next build in a production environment but need a build-time secret that differs from runtime. file was meant for the build server, not for a local machine
| File Name | Purpose | Commit to Git? | | :------------------------ | :---------------------------------------------------------------------------------------------------------------- | :------------- | | .env | Base defaults that are safe to share (e.g., NEXT_PUBLIC_APP_NAME=MyApp ). Serves as a fallback. | Yes (Use with caution—no secrets!) | | .env.local | Local machine overrides for all environments (except test). Ideal for secrets that should never leave your machine, like a personal API key for local development. | No | | .env.development | Development-specific defaults (e.g., a local API URL). Often safe to commit if it contains no secrets. | Maybe | | .env.development.local | Local overrides for the development environment. The highest priority for npm start or npm run dev . | No | | .env.production | Production-specific non-secret defaults (e.g., the URL of your production API). Can be committed if no secrets. | Maybe | | .env.production.local | Local overrides for the production environment. Highest priority for npm run build . commit. | No | | .env.test | Test-specific settings. | Maybe | | .env.test.local | Local overrides for the test environment. | No |
You populate this server file with actual database passwords, private API tokens, and encryption keys. Because it ends in .local , it stays safely on that specific server. Server-Side vs. Client-Side Exposure
In a Node.js project, you would load them early in your entry point:
# .env.production (Committed to Git) NEXT_PUBLIC_API_URL=https://production-domain.com DATABASE_URL=postgresql://readonly_user@localhost/db Use code with caution.