Vite Environment Variables Not Working— Fixed [Complete Guide 2026]
Also covers: import.meta.env undefined · VITE_ prefix · .env file order · TypeScript types
⚡ The Symptom
// In your component:
console.log(import.meta.env.API_URL)
// Output: undefined
// Or TypeScript error:
// Property 'API_URL' does not exist on type 'ImportMeta'✅ Root Cause — Missing VITE_ Prefix
# ❌ Wrong — Vite won't expose this to the browser
API_URL=https://api.example.com
# ✅ Correct — VITE_ prefix is required
VITE_API_URL=https://api.example.comWhy Vite Environment Variables Are Undefined
Vite exposes environment variables to your client-side code through import.meta.env — but only variables prefixed with VITE_. This is a deliberate security boundary: non-prefixed variables (like DATABASE_URL or SECRET_KEY) are kept private and never bundled into your JavaScript output.
If you are migrating from Create React App, this is the key difference: CRA used REACT_APP_ + process.env. Vite uses VITE_ + import.meta.env.
Add the VITE_ Prefix to Every Variable
Root cause — most common fixEvery variable you want accessible in your React/Vue/Svelte code must start with VITE_. Rename the variable in your .env file and update all references in your code.
# Before (invisible to Vite client code)
API_URL=https://api.example.com
STRIPE_KEY=pk_live_abc123
# After (accessible via import.meta.env)
VITE_API_URL=https://api.example.com
VITE_STRIPE_KEY=pk_live_abc123// Before (CRA pattern — does NOT work in Vite)
const BASE = process.env.REACT_APP_API_URL
// After (Vite pattern)
const BASE = import.meta.env.VITE_API_URL
console.log(BASE) // "https://api.example.com"Never put secret keys (private API keys, database passwords) in VITE_ variables. They are inlined into your public JavaScript bundle and visible to anyone who inspects your site.
Create the Correct .env File
File naming and loading orderVite loads .env files from your project root (same folder as vite.config.ts). The correct file names and their loading priority:
# Loaded in all modes
.env
# Loaded in all modes — add to .gitignore
.env.local
# Loaded only in development (npm run dev)
.env.development
.env.development.local
# Loaded only in production (npm run build)
.env.production
.env.production.local# Put this file next to vite.config.ts — NOT inside /src
VITE_API_URL=https://api.example.com
VITE_APP_NAME=My AppAdd .env.local and .env.*.local to your .gitignore — these are meant for per-developer secrets that should never be committed to the repository.
Restart the Dev Server After Every Change
import.meta.env still shows old valuesVite reads .env files only at server startup. Hot Module Replacement (HMR) does not pick up .env changes automatically.
# Stop the dev server (Ctrl + C), then restart:
npm run dev
# Verify the variable is loaded:
# In any component, add temporarily:
console.log(import.meta.env)
# You should see all VITE_ variables in the outputAdd TypeScript Types for import.meta.env
TypeScript: Property does not exist on ImportMetaBy default TypeScript only knows about Vite's built-in import.meta.env properties like MODE and DEV. Add your custom VITE_ variables to the ImportMetaEnv interface for full type safety and autocomplete.
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_URL: string
readonly VITE_STRIPE_KEY: string
readonly VITE_APP_NAME: string
// Add all your VITE_ variables here
}
interface ImportMeta {
readonly env: ImportMetaEnv
}// TypeScript knows the type of each variable
const apiUrl: string = import.meta.env.VITE_API_URL
const appName: string = import.meta.env.VITE_APP_NAMEFix Env Variables in Production Build
Undefined after npm run build / on Vercel / NetlifyVite statically replaces import.meta.env.VITE_* references at build time. If the variable is not set in the environment when npm run build runs, it will be undefined in production.
# Via Vercel CLI
vercel env add VITE_API_URL production
vercel env add VITE_STRIPE_KEY production
# Then redeploy
vercel --prod[build]
command = "npm run build"
publish = "dist"
[build.environment]
VITE_API_URL = "https://api.example.com"
# Or set in Netlify dashboard: Site Settings → Environment Variablesimport { defineConfig, loadEnv } from "vite"
export default defineConfig(({ mode }) => {
const env = loadEnv(mode, process.cwd(), "")
// Fail the build if a required variable is missing
if (!env.VITE_API_URL) {
throw new Error("VITE_API_URL is required but not set")
}
return { /* your config */ }
})Use Env Variables Inside vite.config.ts
process.env doesn't work the same way in configInside vite.config.ts, import.meta.env is not available. Use Vite's loadEnv helper to read .env variables in your config file.
import { defineConfig, loadEnv } from "vite"
import react from "@vitejs/plugin-react"
export default defineConfig(({ mode }) => {
// Load env from the current working directory
const env = loadEnv(mode, process.cwd(), "")
return {
plugins: [react()],
server: {
proxy: {
"/api": {
target: env.VITE_API_URL, // use env vars in config
changeOrigin: true,
},
},
},
}
})Prevention
- Always prefix client-side variables with VITE_ — never use plain process.env in Vite projects
- Commit a .env.example file with all required variable names (no values) so new developers know what to set
- Add .env.local and .env.*.local to .gitignore — never commit real secrets
- Declare all VITE_ variables in src/vite-env.d.ts for TypeScript type safety
- Validate required variables in vite.config.ts using loadEnv — fail fast at build time
- Set production env vars in your deployment platform dashboard before the first deploy
Frequently Asked Questions
Why are my Vite environment variables undefined?+−
How do I access environment variables in Vite?+−
What .env files does Vite load?+−
Do I need to restart the dev server after changing .env?+−
How do I add TypeScript types for Vite env variables?+−
Why do Vite env variables work in dev but not in production?+−
Need Expert Help?
We Build Production-Ready Vite + React Apps
Softplix engineers build and deploy modern frontend applications with Vite, React, and TypeScript. Need help with your build setup or deployment pipeline? We can help.
Talk to an Engineer