skip to content

Env Vars & Assets

import.meta.env exposes only VITE_-prefixed values from .env.[mode] files, while ?url, ?raw and ?worker imports and public/ decide how assets ship. Interviewers ask because env leaks are classic.

on this pageshow

questions

6

In a Vite app, why does `import.meta.env.DONATIONS_SIGNING_KEY` read `undefined` in the browser while `import.meta.env.VITE_API_ORIGIN` has a value?

level: juniorimportance: must knowfreq 26%

answer

  1. what the browser bundle may see
  2. an allow-list by name
  3. a default prefix of five characters
  4. the option that changes the prefix
  5. the empty prefix is refused

basics

~10 s

Vite exposes on import.meta.env only variables whose names start with envPrefix, VITE_ by default, plus built-ins such as MODE, DEV, PROD, SSR and BASE_URL. Any other variable reads as undefined in client code.

solid answer

~40 s

Vite reads the `.env` files and the process environment, then keeps only the names that start with `envPrefix`, which defaults to `VITE_`. Those, plus the built-ins `MODE`, `BASE_URL`, `PROD`, `DEV` and `SSR`, are all that `import.meta.env` holds in client code, so `DONATIONS_SIGNING_KEY` is `undefined`; a production build even replaces the access with the literal `undefined`. The prefix is an allow-list by name: whatever matches is written into the shipped JavaScript. You can change it with `envPrefix: 'APP_'` or an array, but `envPrefix: ''` makes Vite throw rather than expose everything. To expose one unprefixed value, the docs suggest a `define` entry for that single name.

go deeper

for a junior

Recall the default prefix, VITE_, and the five built-ins: MODE, BASE_URL, PROD, DEV and SSR. Say plainly that an unprefixed variable is undefined in browser code.

for a middle

Explain where the values come from: .env files and the process environment, both filtered by envPrefix, then written into the bundle at build time. Mention that an empty prefix throws.

for a senior

Show you treat the prefix as a naming allow-list, not a security boundary: anything prefixed ships to every visitor. Prefer a single define entry over a broad extra prefix for one CI value.

for a principal

Frame envPrefix as a convention a whole organisation can audit: one prefix per meaning, reviewed like an API, so a rename never silently publishes a server-side value.

## What `import.meta.env` is `import.meta` is the standard per-module metadata object, and Vite adds an `env` property to it. During development the values are defined as globals that client modules read. In `vite build` every `import.meta.env.NAME` expression is **statically replaced** with its value as source text, which is what lets the minifier drop a branch such as `if (import.meta.env.DEV) { … }` from production code. ## The built-in constants These exist whatever your `.env` files contain: | Constant | Type | Value | |---|---|---| | `MODE` | string | the mode Vite runs in: `development` for `vite`, `production` for `vite build`, or whatever `--mode` names | | `BASE_URL` | string | the public base path from the `base` option, `/` by default | | `PROD` | boolean | true when `NODE_ENV` is `production` | | `DEV` | boolean | always the opposite of `PROD` | | `SSR` | boolean | true when the code runs in the server environment | ## The prefix rule User variables come from two places: the `.env` files in the env directory and the process environment Vite was started in. From both, Vite keeps only the names that start with an entry of **`envPrefix`**, which defaults to `VITE_`. 1. Vite reads the `.env` files for the current mode and merges them. 2. It keeps the keys that start with a prefix and drops the rest. 3. It adds prefixed variables from the process environment, which override file values. 4. That set, plus the built-ins, is everything client code can read. So with a `.env` holding `VITE_API_ORIGIN=https://api.charity.test` and `DONATIONS_SIGNING_KEY=…`, client code gets the origin and `undefined` for the key. In a production build the unknown access is replaced with the literal `undefined`; nothing is looked up when the page runs. The rule is an **allow-list by name**, not a judgement about sensitivity. Anything you prefix is written into the JavaScript every visitor downloads. Which values may be public at all is a separate decision; Vite only enforces the naming convention. ## Changing the prefix with `envPrefix` `envPrefix` takes a string or an array of strings: - `envPrefix: 'APP_'` exposes `APP_*` names instead of `VITE_*` ones; the default no longer applies once you set the option. - `envPrefix: ['VITE_', 'APP_']` exposes both families. - `envPrefix: ''`, or an array containing `''`, makes Vite **throw** at startup with an error about unexpected exposure of sensitive information. Vite refuses to turn the allow-list into "everything". - A prefix that contains whitespace produces a warning, because it cannot match a real variable name. To expose one unprefixed variable, such as a build number a CI system sets, the docs show the `define` option with `'import.meta.env.BUILD_ID': JSON.stringify(process.env.BUILD_ID)`. That adds exactly one name, whereas an extra prefix exposes every variable that happens to share it, including ones added later by someone else. ## Where the rule shows up beyond JavaScript - **HTML**: `index.html` may use `%VITE_API_ORIGIN%` or `%MODE%`. A name that is not in `import.meta.env` is left as written instead of being replaced. - **`process.env`**: browser code is not Node. In an app build Vite replaces `process.env.NODE_ENV` with the current `NODE_ENV` and `process.env` itself with an empty object, so `process.env.API_ORIGIN` is `undefined` too. - **Shell variables**: `VITE_API_ORIGIN=https://ci.charity.test vite build` is exposed and beats the files, while `API_ORIGIN=… vite build` is not exposed at all. ## Common traps - Renaming a server-side value with `VITE_` "to make it work" publishes it in every built file. - Expecting an edit to `.env` to reach a running dev server at once: the files are read when Vite starts. - Reading `import.meta.env` inside `vite.config.ts`, where the client constants are not populated; the config file reads environment variables its own way. - Assuming a mistyped name fails loudly: `import.meta.env.VITE_API_ORIGN` is simply `undefined`, which is why projects declare their variables in a type file. ## Debugging an unexpected `undefined` When a value you expected is missing in the browser, walk the path it should have taken: 1. **The name**: does it start with an entry of `envPrefix`, spelled exactly, including case? 2. **The file**: is it in a file loaded for the current mode, in the env directory, rather than in `.env.production` while you run the dev server? 3. **The process**: was Vite restarted after the file changed? 4. **The override**: is a variable of the same name exported in the shell or CI job, quietly beating the file? 5. **The output**: after `vite build`, search the emitted JavaScript for the value; if it is there, the build is right and the problem is in the code that reads it. The last step also works the other way round: search the output for a value that should never ship, to confirm that an unprefixed name stayed out.

  • How do you expose a single variable a CI system sets, such as `BUILD_ID`, without renaming it?
    Use the `define` option for that one name: `'import.meta.env.BUILD_ID': JSON.stringify(process.env.BUILD_ID)`, as the docs show. Adding `BUILD_` or a similar prefix to `envPrefix` would also work, but it exposes every variable that starts with that prefix, now and later, so the single `define` entry is the narrower choice.
  • Does the prefix rule also filter variables exported in the shell, or only those in `.env` files?
    Both. Vite applies the same prefix to the process environment: `VITE_API_ORIGIN=https://ci.charity.test vite build` reaches client code and overrides any file value, while an unprefixed shell variable never reaches `import.meta.env`.
  • Can `index.html` use these values?
    Yes. Vite replaces `%NAME%` in HTML with any property of `import.meta.env`, so `%MODE%` or `%VITE_API_ORIGIN%` work. A name that is not in `import.meta.env` is left as written, unlike JavaScript, where the access becomes `undefined`.

  • import.meta.env exposes every variable defined in the project's .env files.
  • Setting envPrefix to an empty string quietly exposes every variable.
  • A variable exported in the shell bypasses the prefix rule and reaches the browser.
  • process.env reads any variable in Vite browser code, just as it does in Node.
  • VITE_ values stay on the server and are fetched by the page at runtime.
open as a page

With `vite build --mode staging`, which `.env` file's `VITE_API_ORIGIN` wins when several define it, and what overrides every file?

level: middleimportance: must knowfreq 17%

basics

~10 s

Vite loads .env, .env.local, .env.staging and .env.staging.local, and the mode files win: .env.staging.local, then .env.staging, then .env.local, then .env. A variable already set in the shell or CI environment beats every file.

open as a page

In a Vite app, why does `if (import.meta.env.VITE_DONATIONS_ENABLED)` still show the donate button when `.env` sets the flag to `false`?

level: juniorimportance: should knowfreq 15%

basics

~10 s

Vite exposes env variables as strings, so VITE_DONATIONS_ENABLED=false arrives as the non-empty string 'false', which is truthy. Compare it explicitly, for example === 'true'. Only built-ins such as DEV, PROD and SSR are booleans.

open as a page

In a Vite app, what do a plain import of `icons.svg` and its `?url`, `?raw` and `?inline` forms each return?

level: middleimportance: should knowfreq 12%

basics

~10 s

All four return strings. A plain import or ?url gives a URL, a hashed file or a data URL below build.assetsInlineLimit (4096 bytes); ?raw gives the file's text; ?inline always gives a data URL.

open as a page

In a Vite app, should a 2 MB GeoJSON file be imported as JSON or fetched by URL, and what must change for `.geojson`?

level: middleimportance: should knowfreq 7%

basics

~20 s

A JSON import puts the data inside a JavaScript chunk; a ?url import keeps it in its own cached file, so fetch 2 MB. Vite treats only .json as JSON: rename the file, use ?url, or add .geojson to assetsInclude.

open as a page

With Vite 8.1 or later, how do `import { plan } from './planner.wasm'` and `./planner.wasm?init` differ, and when do you need `?url` instead?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

Since Vite 8.1 a direct .wasm import is instantiated by Vite and exposes the module's exports as named ES exports. ?init returns a function that instantiates on demand with your imports. Use ?url when you need the WebAssembly.Module itself.

open as a page