Vite environment variables: transitioning from implicit to explicit client-side exposure

Answer the question first

Precedence when a variable is defined in both a mode‑specific .env.[mode] file and the define option: define wins. The define object is applied after all .env files have been parsed, so any value supplied there replaces the one from the file.

Precedence among .env, .env.local, and the system environment: Vite loads files in the following order (each step overrides the previous one):

• .env
• .env.local (overrides .env)
• .env.[mode] (overrides .env and .env.local)
• .env.[mode].local (overrides the mode file)
• Finally, values from process.env are only used if the variable was not set in any of the files above.

Likely explanation

Vite’s environment system is intentionally simple: files are loaded top‑to‑bottom, each subsequent file can override earlier values. The define option is a compile‑time constant replacement and therefore has the highest priority. This design keeps the behaviour predictable when you need to inject hard‑coded values (e.g., feature flags or build metadata) that should not be overridden by local files.

Confirmed facts

1. Only variables prefixed with VITE_ are automatically exposed to the client via import.meta.env.
2. The define option replaces the value of a variable in the final bundle, regardless of its source.
3. Vite loads .env files in the order described above; the system environment is consulted only if no file defines the variable.

Steps to verify the resolution in your project

1. Rebuild the project. Run npm run dev or npm run build so Vite processes the current .env files.
2. Log the variable in the browser.

   console.log(import.meta.env.MY_VAR)

   This shows the value that ends up in the bundle.
3. Check the generated bundle. In dist/assets open the main JS file and search for MY_VAR. The inlined value should match what you saw in the console.
4. If the value differs from what you expect, confirm that the variable is present in .env, .env.local, or vite.config.js and that you have chosen the correct mode (e.g., --mode production).

What to do if you need a variable only for the server

Do not prefix it with VITE_ and avoid adding it to define. Keep it in process.env or in a .env file that is not loaded on the client.

Missing diagnostic detail

To give a more precise recommendation, could you tell me which Vite mode you’re running (e.g., development or production) and whether the variable appears in .env.local or a mode‑specific file? This will help confirm that the precedence order matches your setup.