Vite Environment Variables as a Trust Boundary: Keeping Secrets Out of the Client Bundle

If your Vite-built frontend needs an API key, the first design question is not "where do I put the key" but "is this value allowed to be public at all." Vite's environment variable handling makes that decision concrete: anything referenced through import.meta.env in shipped code is statically inlined into the bundle at build time, and any user can read it. The useful takeaway is that the VITE_ prefix is not a convenience feature — it is the entire trust boundary between public client configuration and server-only secrets, and your architecture should treat it that way.

Requirements

A typical frontend deployment needs three categories of configuration:

• Public config — API base URLs, feature flags, public analytics IDs. Safe for anyone to read.
• Per-environment values — the same key resolving differently in development, staging, and production.
• Secrets — private API keys, signing credentials, database URLs. Must never reach a browser.

The design must keep category three out of the bundle by construction, not by habit, and must make per-environment selection explicit and auditable in CI.

How Vite draws the boundary

Vite loads variables from .env files and the process environment, then exposes them to client code through import.meta.env. Two rules define the boundary:

• Only variables prefixed with VITE_ are exposed to client-side code. VITE_API_URL is visible in the browser; API_URL is not.
• Exposed values are statically replaced during the build. The literal string ends up in your JavaScript output. There is no runtime lookup and no indirection to hide behind.

This means "exposed to the client" and "public to the world" are the same statement. Anyone can open DevTools, search the bundle, and read every VITE_ value. The prefix is a guardrail that forces a deliberate naming decision — it is not access control, and nothing stops a developer from prefixing a secret.

The smallest suitable design

Keep the client dumb. The Vite bundle holds only non-sensitive configuration; every secret-bearing integration lives behind a server or serverless endpoint that the client calls.

# .env (committed, non-sensitive defaults)
VITE_API_BASE_URL=https://api.example.com
VITE_FEATURE_NEW_CHECKOUT=true

# server-only — read via process.env in backend code, never VITE_-prefixed
PAYMENTS_SECRET_KEY=sk_live_...

In client code, reference variables statically so the replacement works:

// src/api.ts — shipped to the browser, so only public values belong here
const baseUrl = import.meta.env.VITE_API_BASE_URL;

export async function createPayment(amount: number) {
  // The secret key stays on the server; the client only calls your endpoint.
  return fetch(`${baseUrl}/payments`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount }),
  });
}

Two access patterns to avoid:

• Dynamic access — import.meta.env[key] cannot be statically replaced and evaluates to undefined. If you need a lookup table, build an explicit object literal of the keys you use.
• Importing server config into the client graph — a module that reads process.env.PAYMENTS_SECRET_KEY is fine in vite.config.ts or backend code, but the moment any client-imported module touches it, the value can leak into the bundle.

Per-environment configuration

Vite loads env files per mode: .env, then .env.[mode], with .local variants (.env.local, .env.[mode].local) layered on top and intended to stay out of version control. The mode comes from --mode (defaults: development for vite, production for vite build).

# Run from the project root; no special permissions needed
vite build --mode staging

This picks up .env.staging and .env.staging.local. Pin the mode explicitly in CI rather than relying on defaults, so a production build can never silently absorb development values because someone changed a script.

Add .env.local and .env.*.local to .gitignore. Committing a local override file is one of the most common ways secrets escape.

Operational checks

Because the boundary is naming-based, verify it after every build pipeline change:

1. Grep the build output for a known secret. After vite build, run from the project root: grep -r "sk_live" dist/ (substitute a distinctive fragment of any real secret). Expected result: no matches. Any match means the secret reached the client graph and must be rotated, not just removed.
2. Confirm only expected keys are inlined. Search dist/assets/*.js for your VITE_ values and confirm the set matches your committed .env files.
3. Diff modes. Build with --mode staging and --mode production and diff the outputs to confirm the intended file took effect.
4. Smoke-test exposure. Create a pair of test variables, one prefixed and one not, log import.meta.env in a component, and confirm only the prefixed one appears.

Failure modes

• Prefixing a secret with VITE_ to "make it work" in the browser. The value is now public; treat it as compromised and rotate it.
• Committing .env.local, which then ships to every developer machine and CI log.
• Assuming runtime changes apply. Values are baked in at build time. Changing an environment variable requires a rebuild and redeploy — restarting the hosting process does nothing. If you genuinely need runtime-configurable values, fetch a config JSON from the server at startup instead of using import.meta.env.
• Dynamic key access silently yielding undefined, often surfacing only in production where the fallback path differs.

When this design changes

Revisit the architecture if you need per-request or per-tenant configuration (move to server-rendered config injection), if values must rotate without redeploys (runtime config endpoint), or if the "public" API surface grows to need rate limiting and abuse controls that a static key cannot provide. Also confirm prefix and file-loading behavior against the documentation for your installed Vite major version — env handling details are version-sensitive, and the checks above are the fastest way to verify them for your setup.