Env Variables and Modes ​

Env Variables ​

Vite exposes env variables on the special import.meta.env object, which are statically replaced at build time. Some built-in variables are available in all cases:

• import.meta.env.MODE : {string} the mode the app is running in.

• import.meta.env.BASE_URL : {string} the base url the app is being served from. This is determined by the base config option .

• import.meta.env.PROD : {boolean} whether the app is running in production (running the dev server with NODE_ENV='production' or running an app built with NODE_ENV='production' ).

• import.meta.env.DEV : {boolean} whether the app is running in development (always the opposite of import.meta.env.PROD )

• import.meta.env.SSR : {boolean} whether the app is running in the server .

.env Files ​

Vite uses dotenv to load additional environment variables from the following files in your environment directory :

.env                # loaded in all cases
.env.local          # loaded in all cases, ignored by git
.env.[mode]         # only loaded in specified mode
.env.[mode].local   # only loaded in specified mode, ignored by git

Loaded env variables are also exposed to your client source code via import.meta.env as strings.

To prevent accidentally leaking env variables to the client, only variables prefixed with VITE_ are exposed to your Vite-processed code. e.g. for the following env variables:

VITE_SOME_KEY=123
DB_PASSWORD=foobar

Only VITE_SOME_KEY will be exposed as import.meta.env.VITE_SOME_KEY to your client source code, but DB_PASSWORD will not.

console.log(import.meta.env.VITE_SOME_KEY) // "123"
console.log(import.meta.env.DB_PASSWORD) // undefined

Also, Vite uses dotenv-expand to expand variables out of the box. To learn more about the syntax, check out their docs .

Note that if you want to use $ inside your environment value, you have to escape it with \ .

KEY=123
NEW_KEY1=test$foo   # test
NEW_KEY2=test\$foo  # test$foo
NEW_KEY3=test$KEY   # test123

If you want to customize the env variables prefix, see the envPrefix option.

IntelliSense for TypeScript ​

By default, Vite provides type definitions for import.meta.env in vite/client.d.ts . While you can define more custom env variables in .env.[mode] files, you may want to get TypeScript IntelliSense for user-defined env variables that are prefixed with VITE_ .

To achieve this, you can create an vite-env.d.ts in src directory, then augment ImportMetaEnv like this:

/// <reference types="vite/client" />
interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  // more env variables...
interface ImportMeta {
  readonly env: ImportMetaEnv
}

If your code relies on types from browser environments such as DOM and WebWorker , you can update the lib field in tsconfig.json .

{
  "lib": ["WebWorker"]
}

HTML Env Replacement ​

Vite also supports replacing env variables in HTML files. Any properties in import.meta.env can be used in HTML files with a special %ENV_NAME% syntax:

<h1>Vite is running in %MODE%</h1>
<p>Using data from %VITE_API_URL%</p>

If the env doesn't exist in import.meta.env , e.g. %NON_EXISTENT% , it will be ignored and not replaced, unlike import.meta.env.NON_EXISTENT in JS where it's replaced as undefined .

Given that Vite is used by many frameworks, it is intentionally unopinionated about complex replacements like conditionals. Vite can be extended using an existing userland plugin or a custom plugin that implements the transformIndexHtml hook .

Modes ​

By default, the dev server ( dev command) runs in development mode and the build command runs in production mode.

This means when running vite build , it will load the env variables from .env.production if there is one:

# .env.production
VITE_APP_TITLE=My App

In your app, you can render the title using import.meta.env.VITE_APP_TITLE .

In some cases, you may want to run vite build with a different mode to render a different title. You can overwrite the default mode used for a command by passing the --mode option flag. For example, if you want to build your app for a staging mode:

vite build --mode staging

And create a .env.staging file:

# .env.staging