Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Project Structure and Config

Modes and Environment Variables

Use .env files and import.meta.env in Vite, understand the VITE_ prefix, built-in constants such as MODE and PROD, custom modes, and why env values are never secret in client code.

Apps behave differently in different places. A development build talks to a local API, a staging build to a test server, and the production build to the real one. Vite handles this with modes and environment variables loaded from .env files, and exposes them in your code through import.meta.env. The most important thing to learn is not the syntax but the safety rule: anything exposed to the browser is public.

Vite is not installed on this site, so .env file listings are read-only. The runnable examples are Node.js stand-ins that apply the same loading and filtering rules.

import.meta.env

In your source code, Vite replaces import.meta.env with an object. These built-in values are always present:

Property Type Meaning
import.meta.env.MODE string The mode (development, production or custom)
import.meta.env.BASE_URL string The base option (e.g. / or /docs/)
import.meta.env.PROD boolean true in production
import.meta.env.DEV boolean true in development (the opposite of PROD)
import.meta.env.SSR boolean true when running on the server
JavaScript
if (import.meta.env.DEV) {
  console.log('Running in development, mode:', import.meta.env.MODE);
}

In production builds, import.meta.env.DEV becomes the literal false, so the minifier removes that whole branch. That is called dead code elimination: development-only logging does not ship.

.env files

Vite loads variables from files in your project root (envDir):

TEXT
.env                 loaded in all cases
.env.local           loaded in all cases, ignored by git
.env.[mode]          loaded only in the given mode
.env.[mode].local    loaded only in the given mode, ignored by git

Priority, from highest to lowest: .env.[mode].local, .env.[mode], .env.local, .env. Variables that already exist in the process environment (such as ones set by your CI system) win over all files.

Example:

INI
# .env
VITE_APP_TITLE=My App
VITE_API_URL=http://localhost:8000

# .env.production
VITE_API_URL=https://api.example.com

# .env.local  (never commit this one)
DB_PASSWORD=super-secret

Add *.local to .gitignore. Vite's own scaffolds already do that.

The VITE_ prefix: what is exposed

Only variables whose names start with VITE_ are exposed to your client code:

JavaScript
console.log(import.meta.env.VITE_API_URL);   // "http://localhost:8000"
console.log(import.meta.env.DB_PASSWORD);    // undefined: not exposed

This is a safety feature. If every variable were exposed, one careless .env line would publish a database password inside your JavaScript. You can change the prefix with envPrefix in the config, but never set it to an empty string.

Everything exposed to the browser is public. Anyone can open DevTools or read your bundle and see VITE_* values. Use env variables for settings such as API base URLs and public keys (a publishable Stripe key is fine), never for private API keys or database credentials. Secrets belong on a server.

Seeing the loading rules

This stand-in applies the precedence and prefix rules to fake files, so you can predict what your code will see. It is a model, not Vite's real loader.

Node.js Stand-in: which values reach import.meta.env?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Custom modes

The mode is just a label. To create a staging mode, add .env.staging and run:

Terminal
vite build --mode staging

Now import.meta.env.MODE is 'staging', and .env.staging is loaded. Note that PROD stays true because vite build sets NODE_ENV=production, unless you pass --mode development together with an explicit NODE_ENV. The mode and NODE_ENV are separate things: the mode picks the env files, NODE_ENV controls whether framework dev helpers and minification apply.

Typical scripts:

JSON
{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "build:staging": "vite build --mode staging",
    "test": "vitest --mode test"
  }
}

Expanding variables and types

Vite expands references to other variables in .env files (using dotenv-expand):

INI
VITE_HOST=api.example.com
VITE_API_URL=https://$VITE_HOST/v1

For TypeScript, add types so your editor knows the variable names. Create src/vite-env.d.ts:

TypeScript
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
  readonly VITE_TITLE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Values are always strings. VITE_ENABLE_DEBUG=false gives the string 'false', which is truthy! Convert deliberately:

Node.js Env values are strings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

HTML env replacement

Vite also replaces %VARIABLE% patterns in index.html:

HTML
<title>%VITE_APP_TITLE%</title>

If the variable does not exist, the text stays as written. Use it for titles, analytics IDs and similar settings.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which variable is visible as import.meta.env.X in client code?

    Only variables beginning with VITE_ (by default) are exposed. Others stay on the Node side.
  2. 2. Which file wins when the same variable is defined in .env and .env.production, in production mode?

    Mode-specific files have higher priority than .env, and .local variants are higher still.
  3. 3. What is the type of import.meta.env.VITE_ENABLE_DEBUG when the file says VITE_ENABLE_DEBUG=false?

    Env values are strings. 'false' is truthy, so compare against 'true' explicitly.
  4. 4. Why is putting a private API key in a VITE_ variable a mistake?

    Browser code is public. Keep secrets on a server and expose only non-sensitive configuration.

Summary

  • import.meta.env provides MODE, BASE_URL, PROD, DEV, SSR and your VITE_* variables.
  • .env, .env.local, .env.[mode] and .env.[mode].local are loaded with later, more specific files winning.
  • Only VITE_-prefixed variables reach the browser, and they are public, so never store secrets there.
  • Use --mode for custom environments such as staging; values are always strings.
  • Add types in vite-env.d.ts and use %VITE_X% in index.html if needed.

Next: Aliases and Path Resolution