Vite env variables: VITE_ prefix and .env modes

Vite reads variables from the shell and from .env, .env.local, .env.[mode] and .env.[mode].local, then exposes the ones that start with VITE_ to your code as import.meta.env.VITE_*. During vite build those references are replaced with literal strings, so a Vite app's values are fixed at build time and every VITE_ value is readable by anyone who loads the page. Variables already present in the shell beat every file. These rules come from the Vite guide on env variables and modes, which describes Vite 8 as of October 30, 2026.

Files, modes and who wins

Vite loads four files from the project root, or from the directory set by envDir:

A file for a specific mode takes priority over a generic one, and the .local variants are meant for values that never leave your machine. Above all of them sits the environment Vite was started in: a variable that exists when Vite runs is never overwritten by any file. VITE_SOME_KEY=123 vite build wins over every .env* file.

The mode is development for the dev server and production for vite build, unless you pass --mode. A staging mode would load .env.staging and .env.staging.local.

Mode is not NODE_ENV

People often expect vite build --mode staging to produce a non-production build. It doesn't change NODE_ENV, which stays production:

import.meta.env.PROD follows NODE_ENV, while import.meta.env.MODE follows --mode. If staging needs different API endpoints, read them from VITE_ variables in .env.staging and branch on MODE, not on PROD.

What actually lands in the bundle

Vite exposes these values through import.meta.env:

• the built-in constants MODE, BASE_URL, PROD, DEV and SSR;
• every variable whose name starts with VITE_, or with the prefix you set in envPrefix.

In development they're defined as globals. In vite build they're statically replaced, which lets the bundler drop dead branches. The result is that import.meta.env.VITE_API_URL becomes the string "https://api.example.com" in the output file.

The Vite guide is blunt about the consequence: VITE_* variables should not contain sensitive information such as API keys. A variable without the prefix, such as DB_PASSWORD, comes back as undefined in client code, which is the protection. Renaming it to VITE_DB_PASSWORD to "make it work" publishes it.

Two smaller details:

• Everything is a string. VITE_RETRIES=3 arrives as "3", and VITE_DEBUG=false as the non-empty string "false". Convert explicitly.
• Variables expand. Vite runs dotenv-expand, so $OTHER inside a value is replaced. Escape a literal dollar sign as \$.

Before you add a VITE_ variable

Because the prefix is the only thing between a value and the public bundle, it's worth a short check every time someone adds one:

• Would you put this value in a public web page? If not, it doesn't get the prefix. The browser should call an endpoint you control, which holds the real key.
• Is it different per stage? Then it belongs in .env.[mode] or in the build environment, not hard-coded, and each stage needs its own build.
• Does anyone change it often? Every change means a rebuild and a redeploy, so a frequently changing value is better fetched at runtime from your API.
• Is the name listed in .env.example? New teammates and CI need to know the variable exists, even though the value lives elsewhere.

If you changed envPrefix, apply the same check to the new prefix. A broad prefix exposes more variables than you expect, and anything that matches it goes into the bundle.

Restarts, Bun and other surprises

.env files are read when Vite starts. Editing .env.local while vite is running changes nothing until you restart it.

If you run Vite through Bun, Bun loads .env files into process.env before Vite starts. Vite respects existing process.env values, so the values Bun loaded look like shell variables and outrank Vite's own mode files. The Vite guide flags this, and the Bun page shows how to turn Bun's loading off.

The config file is evaluated before Vite loads env files, so vite.config can't simply read .env.production through process.env. Setting NODE_ENV on the command line lets Vite detect it early.

Build a Vite app with values from Crunu

Because a Vite app's values are fixed during the build, the place to inject them is the build command. crunu run decrypts an environment in memory and starts the build with its variables in the process environment, where Vite gives them top priority over any .env file. Each stage gets its own Crunu environment and its own key, so a developer who builds against storefront/development never holds the production values.

Keep the values honest about what they are. Everything in a Crunu environment that your Vite build reads with the VITE_ prefix becomes public the moment the site is deployed. Crunu protects the values on the way to the build and controls who can change them. It can't make a public variable private. Put real secrets in a separate environment that only your backend reads.

--restart on-change doesn't help here either: a built Vite site is a folder of static files. To change a value, run the build again.

When this setup is worth it

For a small static site with one public analytics ID, a committed .env.production is fine because nothing in it is secret. Crunu pays off when the same repository builds for several stages, when build-time values include things you don't want in Git history, such as a token that uploads source maps to an error tracker, or when people come and go and you need to know who could read which values. See how to share .env files with your team for the trade-offs.

Related reading

• Next.js inlines NEXT_PUBLIC_ the same way, but can also read server values per request.
• SvelteKit and Astro build on Vite's loader and add their own rules.
• What a public env variable is and what a .env file is.
• crunu run and a service token in any CI.