Vite Env Undefined in Production: Fix It at Build Time

Check the five common boundaries#

The Vite environment and mode guide is the source of truth for these loading rules. Do not debug all five boundaries by changing the deployment platform at once; verify them in order.

Use import.meta.env and expose only public values#

Given this .env file:

1
VITE_API_URL=https://api.example.com
2
DATABASE_PASSWORD=not-for-the-browser

Read the values like this:

1
const apiUrl = import.meta.env.VITE_API_URL;
2
const databasePassword = import.meta.env.DATABASE_PASSWORD;
3

4
console.log(apiUrl); // a string
5
console.log(databasePassword); // undefined in client code

The VITE_ prefix is an exposure rule, not a security mechanism. Anything exposed under that prefix is bundled into code that a visitor can download. API keys, database passwords, private tokens, and signing secrets do not belong in VITE_* variables.

If your project needs a different public prefix, configure Vite’s envPrefix deliberately and review the result as part of a security check. A broader prefix makes accidental exposure easier.

Load environment values inside vite.config.*#

Application code and config evaluation are separate boundaries. Vite resolves vite.config.* before .env* values are automatically loaded into process.env. If the config itself needs a .env value, load it with loadEnv using the current mode:

1
import { defineConfig, loadEnv } from 'vite';
2

3
export default defineConfig(({ mode }) => {
4
  const env = loadEnv(mode, process.cwd(), 'VITE_');
5

6
  return {
7
    define: {
8
      __API_URL__: JSON.stringify(env.VITE_API_URL),
9
    },
10
  };
11
});

This example assumes process.cwd() is the Vite project root. If the config uses a different envDir, pass that directory to loadEnv. If only browser code needs the value, keep using the literal import.meta.env.VITE_API_URL reference instead of moving server-side values into the client bundle.

Match the .env file to the build mode#

Vite loads the general files and then the mode-specific files:

1
.env
2
.env.local
3
.env.[mode]
4
.env.[mode].local

For a staging build, make the mode explicit:

1
pnpm exec vite build --mode staging

Then place the public value in .env.staging or inject it into the build environment:

1
VITE_API_URL=https://staging-api.example.com

The mode is a build input. If a CI job runs the default production build, .env.staging will not be the file that supplies its values. Existing process environment variables also take precedence, so a stale CI variable can override a correct file.

Treat static deployment variables as build inputs#

For a static Vite site, this sequence matters:

1
environment variables -> vite build -> JavaScript and HTML assets -> CDN

If you change VITE_API_URL in a hosting dashboard after the build has finished, the old bundle remains unchanged until the build runs again. Rebuild and redeploy, then verify the generated site rather than only checking the dashboard setting.

When the value must change at runtime without rebuilding, use a runtime configuration endpoint or server-rendered value instead of pretending a static client bundle has live access to the host environment. Keep the runtime response limited to values that are safe for the browser.

Make missing configuration fail clearly#

Do not wait for a production request to reveal a missing URL. Centralize the check:

1
const apiUrl = import.meta.env.VITE_API_URL;
2

3
if (!apiUrl) {
4
  throw new Error('VITE_API_URL is missing from this build');
5
}
6

7
export const config = { apiUrl };

For a more defensive build, add a CI check that prints the variable name and whether it exists, never its secret value. The check should run before the bundler so the failure points to configuration instead of a later network error.

In a CI job that injects VITE_API_URL, fail before the bundler if the variable is absent:

1
test -n "${VITE_API_URL:-}" || {
2
  echo "VITE_API_URL is missing before vite build"
3
  exit 1
4
}
5
pnpm exec vite build --mode production

To verify the boundary without printing a real URL, use a non-secret marker in an isolated build:

1
VITE_API_URL=https://api.example.test pnpm exec vite build --mode production
2
rg -n 'api\.example\.test' dist/

A match proves that this public marker entered the generated assets. No match means the exact marker was not emitted as a contiguous string; check the selected mode, envDir, and final build directory before inspecting the host dashboard.

If the project is an Astro app, keep the Vite client/server boundary in mind: browser-exposed values and server-only values do not have the same safety requirements. The site’s Vite manualChunks migration guide is a related build-time troubleshooting example, while Astro’s base-path guide covers a different static-build boundary.

FAQ#