vite-plugin-environment

To expose a specific list of environment variables, pass an array of variable names to EnvironmentPlugin. These variables will be accessible in your client code via process.env.

import { defineConfig } from 'vite'
import EnvironmentPlugin from 'vite-plugin-environment'

export default defineConfig({
  plugins: [
    EnvironmentPlugin(['API_KEY', 'DEBUG']),
  ],
})

Usage in client code:

const apiKey = process.env.API_KEY

Install the package as a development dependency using npm or yarn.

npm i -D vite-plugin-environment # yarn add -D vite-plugin-environment

When passing an object as the first argument to EnvironmentPlugin, you can specify default values for variables. This prevents the build from failing if a variable is missing from the environment.

• Use undefined for required variables: The build will throw an error if the variable is missing.
• Use null for optional variables: The variable will be assigned null if missing.
• Use a string for a specific default value.

Note: While booleans or numbers can technically be passed, all process.env values are strings; using other types may lead to subtle bugs.

import EnvironmentPlugin from 'vite-plugin-environment'

export default EnvironmentPlugin({
  API_URL: 'https://api.example.com', // Default string
  OPTIONAL_KEY: null,                 // Optional variable
  REQUIRED_KEY: undefined,            // Required variable (throws error if missing)
})

To load all environment variables that start with a specific prefix, pass the string 'all' as the first argument and provide a prefix option in the configuration object.

EnvironmentPlugin('all', { prefix: 'VUE_APP_' })
EnvironmentPlugin('all', { prefix: 'REACT_APP_' })

Usage:

process.env.VUE_APP_NOT_SECRET_CODE

By default, variables are exposed on process.env. To expose them on a different object, such as import.meta.env (useful for SSR or porting apps), use the defineOn option.

EnvironmentPlugin({ APP_VERSION: 'local' }, { defineOn: 'import.meta.env' })

Usage:

const version = import.meta.env.APP_VERSION

You can pass an object to EnvironmentPlugin to map keys to default values. The default value is only used if the environment variable is not defined.

• Use undefined for required variables: the build will fail if the variable is missing.
• Use null for optional variables: the build will not fail if the variable is missing.
• Note: Variables coming from process.env are always strings.

EnvironmentPlugin({
  // Uses 'development' if the NODE_ENV environment variable is not defined.
  NODE_ENV: 'development',

  // Variables from process.env are always strings.
  DEBUG: 'false',

  // Required: will fail if the API_KEY environment variable is not provided.
  API_KEY: undefined, 

  // Optional: will not fail if the APP_VERSION environment variable is missing.
  APP_VERSION: null,
})

By default, the plugin uses Vite's strategy to load .env files. To ignore .env files and only use values present in the system's process.env, set loadEnvFiles to false in the configuration object.

EnvironmentPlugin(['API_KEY'], { loadEnvFiles: false })

The EnvironmentPlugin accepts an optional EnvOptions object to control how variables are loaded and exposed:

• prefix (string, default: ''): Only variables starting with this prefix will be made available. Useful for filtering process.env.
• defineOn (string, default: 'process.env'): The object path where variables will be defined in your client code (e.g., 'import.meta.env').
• loadEnvFiles (boolean, default: true): Whether to use Vite's loadEnv to load variables from .env files. If set to false, it falls back to using only process.env filtered by the prefix.

EnvironmentPlugin('all', { 
  prefix: 'VUE_APP_', 
  defineOn: 'import.meta.env', 
  loadEnvFiles: true 
})

The EnvironmentPlugin function allows you to expose specific environment variables (or all variables matching a prefix) to your client-side code via Vite's define mechanism. You can choose to expose them on process.env (default) or import.meta.env.

import EnvironmentPlugin from 'vite-plugin-environment'

// Expose specific variables with default values
export default EnvironmentPlugin(['NODE_ENV', 'API_URL'], { 
  defineOn: 'import.meta.env' 
})

// Or expose all variables matching a prefix
export default EnvironmentPlugin('all', { prefix: 'VUE_APP_' })

The following types define the shape of the arguments passed to EnvironmentPlugin:

• EnvVarDefault: string | null | undefined
• EnvVarDefaults: Record<string, EnvVarDefault>
• EnvVars: 'all' | string[] | EnvVarDefaults