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`?
answer
- what type a parsed value has
- truthiness of a non-empty string
- booleans only among the built-ins
- compare against the literal text
- the type file cannot convert
basics
~10 sVite 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.
solid answer
~30 sVite parses `.env` files into strings and exposes them on `import.meta.env` unchanged, so `VITE_DONATIONS_ENABLED=false` becomes `'false'`, a non-empty string and therefore truthy; `0` becomes `'0'` the same way. The fix is to convert at one boundary, for example `import.meta.env.VITE_DONATIONS_ENABLED === 'true'`, and import that boolean everywhere else. The built-ins `DEV`, `PROD` and `SSR` are real booleans, and `MODE` and `BASE_URL` are strings. Declaring the variable in `ImportMetaEnv` in a `vite-env.d.ts` file gives you IntelliSense, but declaring it as `boolean` would only make the type lie; it should stay `string`.
code
typescript · 14 lines// src/vite-env.d.ts (no import statements in this file)
interface ViteTypeOptions {
strictImportMetaEnv: unknown
}
interface ImportMetaEnv {
readonly VITE_DONATIONS_ENABLED: string
}
interface ImportMeta {
readonly env: ImportMetaEnv
}
// src/config/flags.ts
export const donationsEnabled =
import.meta.env.VITE_DONATIONS_ENABLED === 'true'go deeper
Recall that every value you define arrives as a string, so 'false' is truthy. Write the explicit comparison with 'true' without being prompted.
Explain where the string comes from, why only DEV, PROD and SSR are booleans, and how to convert once in a flags module that the rest of the app imports.
Show that you prevent the class of bug: string types in ImportMetaEnv, strictImportMetaEnv for typos, and a deliberate, documented default when a flag is missing.
Treat build-time flags as a shared contract across apps: one parsing convention, typed declarations and an agreed default, so no team rediscovers truthy 'false' in production.
## Why the flag is a string A `.env` file is plain text: each line is a name, an equals sign and some characters. Vite parses those lines into a map of **strings** and exposes the ones whose names carry the `VITE_` prefix on `import.meta.env`. Nothing in that path knows that `false` was meant as a boolean or `25` as a number. The docs say it directly: a value that looks like a number or a boolean still comes back as a string, and you convert it yourself. JavaScript then applies its usual truthiness rule. Every non-empty string is truthy, so `'false'` and `'0'` both pass an `if`. That is why the donate button stays visible. ## What a flag can actually be | Line in `.env` | `import.meta.env.VITE_DONATIONS_ENABLED` | In an `if` | |---|---|---| | `VITE_DONATIONS_ENABLED=true` | `'true'` | truthy | | `VITE_DONATIONS_ENABLED=false` | `'false'` | **truthy** | | `VITE_DONATIONS_ENABLED=0` | `'0'` | **truthy** | | `VITE_DONATIONS_ENABLED=` | `''` | falsy | | (not set anywhere) | `undefined` | falsy | The built-ins are the exception. `DEV`, `PROD` and `SSR` are booleans, and `MODE` and `BASE_URL` are strings, so `if (import.meta.env.DEV)` behaves as it reads. ## Why Vite does not convert for you A loader that guessed types would break other values. A postcode such as `VITE_OFFICE_ZIP=01234` must keep its leading zero; a version such as `VITE_RELEASE=1.10` would become `1.1` as a number; a word such as `VITE_THEME=null` would turn into something else entirely. Only the code that uses a value knows what it means, so Vite hands over the text and leaves the meaning to you. The same text appears wherever the value is used: `%VITE_DONATIONS_ENABLED%` in `index.html` renders the characters `false`. ## Converting at one boundary The robust pattern is a small module that reads each variable once, converts it and exports a typed value: 1. Read the raw string from `import.meta.env`. 2. Compare it with the exact text you accept, `'true'`, so any other value means off. 3. Export the boolean and import it wherever the flag is used. Comparing with `=== 'true'` makes a missing or misspelt value mean off. If the flag should default to on, compare with `!== 'false'` instead, and write that choice down. Numbers follow the same idea: `Number(import.meta.env.VITE_MAX_GIFT)` with a check for `NaN`. ## Typing it with `ImportMetaEnv` Vite ships types for `import.meta.env` through `vite/client`. To describe your own variables, add a declaration file such as `src/vite-env.d.ts` that augments the `ImportMetaEnv` interface: - Declare each variable as `readonly VITE_DONATIONS_ENABLED: string`. Declaring it `boolean` changes nothing at runtime; it only hides the bug from the compiler. - Without further setup, unknown keys are typed loosely, so a misspelt name still compiles. Adding `strictImportMetaEnv: unknown` to the `ViteTypeOptions` interface makes unknown keys an error. - Keep `import` statements out of that file; an import turns it into a module and the augmentation stops applying. ## Other parsing surprises - Vite expands variables written inside values: `VITE_THANKS=Thanks $DONOR` becomes `Thanks ` when `DONOR` is not defined. Write `\$` to keep a literal dollar sign. - The files are read when Vite starts, so editing `.env` while the dev server runs does not change values until it restarts. - A value set in the shell, such as `VITE_DONATIONS_ENABLED=false vite build`, is a string too; the shell does not pass types either. ## Why the bug survives review The truthiness check passes every test anyone thinks to run. With the flag set to `true` the button shows, as intended; with the flag absent the button hides, as intended. Only the case someone actually reaches for when switching the feature off, writing `false`, behaves wrongly, and it tends to happen on the day a campaign is paused, in production. A test that sets the flag to the literal text `false` and expects the button to be hidden catches it at once. ## A checklist for every flag 1. Declare it as `string` in `ImportMetaEnv`. 2. Convert it in one module, with an explicit comparison. 3. Decide, and write down, what a missing value means. 4. Never test the raw value for truthiness anywhere else.
- Which values on `import.meta.env` are not strings?Only built-ins: `DEV`, `PROD` and `SSR` are booleans. `MODE` and `BASE_URL` are strings, and every variable you define, from a `.env` file or the shell, is a string or `undefined` when it is not set.
- How do you make TypeScript reject a misspelt `import.meta.env.VITE_DONATIONS_ENABLD`?Augment `ImportMetaEnv` with the variables you use, and add `strictImportMetaEnv: unknown` to the `ViteTypeOptions` interface in the same declaration file. Unknown keys then become a type error instead of a loosely typed value that compiles.
- A `.env` line reads `VITE_THANKS=Thanks $DONOR`; why does the page show only `Thanks `?Vite expands `$NAME` references inside values, and `DONOR` is not defined, so it expands to an empty string. Escape the dollar sign as `\$DONOR` to keep it literal.
- Vite turns true and false in .env files into real booleans.
- Typing the variable as boolean in ImportMetaEnv makes its value a boolean.
- Setting the flag to 0 hides the button because zero is falsy.
- import.meta.env.DEV is a string like every other env value.
- Wrapping the value in Boolean() fixes the false flag.