The purpose of a .local suffix is to create a . Any variable defined in a .local file will overwrite the same variable defined elsewhere. These files are meant for configuration specific to your local machine and should never be committed to version control (always add *.local to your .gitignore ).
: Specifies a local override . This file is machine-specific and is designed to bypass the default, committed environment settings.
Vite uses dotenv and dotenv-expand under the hood. To load environment variables in Vite, you use import.meta.env . When running vite build , Vite will load .env.production and .env.local.production . Note that Vite requires variables to be prefixed with VITE_ to be exposed to your client-side code. Summary Checklist for Developers
. Often, a codebase behaves differently in "development" mode (where hot-reloading and debugging are active) than in "production" mode (where code is minified and optimized). When a developer runs a command like next build && next start .env.local.production
It fits into the priority ladder like this (higher priority overrides lower):
Environment variables are the bedrock of modern web development. They keep your API keys hidden, your database credentials secure, and your codebase adaptable across different deployment stages.
Overriding a shared teammate's production variable temporarily on your own machine without altering the codebase for the rest of the team. What to Put Inside the File The purpose of a
Do not put application logic inside environment variable files. They are for configuration, not code. The value of an environment variable should be a simple string, number, or boolean. Complex data structures should be serialized (e.g., as JSON strings) if necessary.
Vite, for example, has a clear loading priority: .env < .env.local < .env.* < .env.*.local .
To test your application using these specific variables, compile and run the optimized production bundle locally: npm run build npm run start Use code with caution. : Specifies a local override
If you are using a framework like Next.js or Vite, environment variable loading is built-in. For a plain Node.js project, you would install dotenv :
Note: If .env.local.production is supported by your specific framework loader (custom plugins or specific Next.js versions), it usually sits at the top of the priority chain for production builds, overriding .env.production .
In both frameworks, a file named .env.local.production is not part of the standard hierarchy. It will be skipped.