Recommended Free Tools
If a value in .env.local seems unchanged, check the file’s location, variable name and framework-specific access syntax first. Then check which environment source takes precedence and whether the running process needs a restart—or a client bundle needs to be rebuilt. Next.js and Vite load and expose environment variables differently, so the right fix depends on where the value is read and when the app was built.
Start with the file location and variable name
Place .env.local in the project root, alongside the package configuration—not inside src. Next.js keeps environment files at the root even when the application code lives in src. See the Next.js environment-variable guide.
As an Amazon Associate I earn from qualifying purchases.
Next, confirm that the code uses the right name and access form for its framework and execution context:
| Framework and context | Client-visible prefix | Access form |
|---|---|---|
| Next.js browser code | NEXT_PUBLIC_ |
process.env.NEXT_PUBLIC_NAME |
| Vite browser code | VITE_ |
import.meta.env.VITE_NAME |
| Server-side code | No browser prefix required | Read the server environment; in Next.js, for example, use process.env.NAME |
Unprefixed values are not exposed to browser code by default. In Next.js, public environment references must use a statically named property such as process.env.NEXT_PUBLIC_API_URL; do not expect a dynamically assembled property lookup to be inlined. Vite exposes prefixed values through import.meta.env. Its environment and mode guide documents this behavior, and the Next.js Vite migration guide outlines the differing access syntax.
#1 Best Overall
Check which source is supplying the value
An env file is not necessarily the winning source. A variable already present in the process environment—such as one set by a shell, container, IDE, or package script—can take precedence over the file you edited. Look for duplicate definitions and inspect the environment of the process actually running the app.
Next.js precedence
Next.js checks these sources in order, from highest to lowest priority:
Rank #2
process.env.env.$(NODE_ENV).local.env.local, except whenNODE_ENVistest.env.$(NODE_ENV).env
If the same key appears in more than one source, the first source in that order wins. For example, a value exported by the shell can override the value in .env.local. The ordering and test-mode exception are documented in the Next.js environment-variable guide.
Vite precedence and mode-specific files
Vite loads .env, .env.local, .env.[mode], and .env.[mode].local from its environment directory. Mode-specific files override generic env files; variables already present in the process environment have higher priority than values from env files. Check the command that launched Vite, its active mode, and any shell, container, IDE, or script settings for the same key.
If you use Bun, Vite’s guide notes that Bun may load env files before Vite starts, which can affect the values Vite sees. The details are in Vite’s environment and mode guide.
Match the fix to when the value is read
For Vite, restart after editing an env file
Vite loads env files when it starts. Stop the dev server and start it again after changing .env.local or another env file. Refreshing the browser alone does not reload the file. Vite states this directly in its environment and mode guide.
Rank #4
For Next.js, restart development or rebuild the public client value
If a Next.js development process is still using values loaded at startup, restart it after editing the env file. For a browser-visible NEXT_PUBLIC_ value in a production app, rebuild the application and deploy the refreshed artifact: Next.js replaces those references during next build. Changing the deployment environment after that build does not update the value already embedded in the client bundle.
Server-side runtime configuration is different. Next.js documents reading environment variables during dynamic rendering so a server can use runtime values. Whether that applies depends on how the route is rendered; a value baked into a static or prebuilt artifact will not become dynamic just because the server later receives a new environment value. See the Next.js self-hosting guide and the environment-variable guide.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Do not confuse Vite mode with NODE_ENV
Vite’s mode selects mode-specific env files and sets import.meta.env.MODE. It is separate from NODE_ENV, which affects flags such as import.meta.env.PROD and import.meta.env.DEV. By default, vite runs in development mode and vite build runs in production mode. A command such as vite build --mode development selects development mode but still uses production NODE_ENV by default.
When a value or conditional looks wrong, check both the active mode and NODE_ENV, rather than assuming one determines the other. Vite explains the distinction in its environment and mode guide; the Vite 5 guide provides the version-specific reference for projects still using that major version.
Keep secrets out of client-exposed variables
Anything exposed with NEXT_PUBLIC_ or VITE_ can be included in browser code. Treat those values as public: do not put API secrets, private tokens, passwords, or other credentials behind either prefix. Keep secrets server-side and access them from server code. Next.js also notes that values configured through the env option in next.config.js are substituted into JavaScript at build time; that option is not a way to hide a secret. See the Next.js env configuration reference.
Quick Recap
A quick diagnostic sequence
- Confirm
.env.localis at the project root. - Check the exact spelling of the key and use
NEXT_PUBLIC_withprocess.envfor Next.js browser code, orVITE_withimport.meta.envfor Vite browser code. - Search for duplicate definitions in process variables and higher-priority or mode-specific env files.
- Check the active framework process and execution context: browser, server, development server, build, or deployed artifact.
- Restart Vite after editing an env file. Restart Next.js development if it is using stale loaded values; rebuild and redeploy when a public Next.js client value was fixed into an existing build.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
