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?
answer
- what the browser bundle may see
- an allow-list by name
- a default prefix of five characters
- the option that changes the prefix
- the empty prefix is refused
basics
~10 sVite 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 sVite 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
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.
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.
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.
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.