vite-plugin-environment

1.1.3 verified Mon Apr 27 auth: no javascript

A Vite.js plugin (v1.1.3) that exposes environment variables to client code without requiring the VITE_ prefix. It acts as a shorthand for Vite's define option, similar to webpack's EnvironmentPlugin. Supports loading prefixed variables, custom define targets (import.meta.env), default values, optional/null handling, and .env file loading (on by default). Currently stable with monthly releases. Differentiates from Vite's built-in import.meta.env by allowing process.env usage and arbitrary variable names.

Common errors

error Error: Cannot find module 'vite-plugin-environment' ↓

cause Package not installed or missing from package.json

fix

Run npm install -D vite-plugin-environment or yarn add -D vite-plugin-environment

error ReferenceError: process is not defined ↓

cause Using process.env in browser context without polyfill; plugin expects Vite's define to work

fix

Ensure plugin is properly loaded in vite.config.js, and check that the variable is defined in process.env during build

error TypeError: EnvironmentPlugin is not a function ↓

cause Using require() on an ESM-only package

fix

Use import statement: import EnvironmentPlugin from 'vite-plugin-environment'

error vite-plugin-environment: Environment variable "API_KEY" is not defined ↓

cause Variable is missing from process.env and has no default (undefined)

fix

Define the variable in your .env file or provide a default value in EnvironmentPlugin({ API_KEY: 'default' })

Warnings

breaking Requires Vite >= 2.7; older versions may break or behave unexpectedly ↓

fix Upgrade Vite to at least 2.7

gotcha Variables exposed via this plugin are stringified; booleans/numbers become strings (e.g., DEBUG:'false' becomes string 'false') ↓

fix Explicitly parse booleans/numbers in client code: const debug = process.env.DEBUG === 'true'

gotcha Passing 'all' as first argument loads ALL env variables; can unintentionally expose secrets if not filtered properly ↓

fix Use specific array of variable names or prefix option to limit exposure

gotcha Default values object: use null for optional, undefined for required. Mixing them up causes unintended failures ↓

fix Explicitly set null for optional variables, undefined (or omit) for required

deprecated No deprecation warnings known in current version

Install

npm install vite-plugin-environment

yarn add vite-plugin-environment

pnpm add vite-plugin-environment

Imports

default

wrong

const EnvironmentPlugin = require('vite-plugin-environment')

correct

import EnvironmentPlugin from 'vite-plugin-environment'

ESM-only package; requires import syntax

type

import type { EnvironmentPluginOptions } from 'vite-plugin-environment'

TypeScript types shipped; use import type for type-only usage

default (CommonJS)

wrong

const EnvironmentPlugin = require('vite-plugin-environment').default

correct

import EnvironmentPlugin from 'vite-plugin-environment'

No CJS build; require() fails with ERR_REQUIRE_ESM. Use dynamic import() if needed.

Quickstart

Shows basic usage: expose two environment variables to client code as process.env.*

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

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

// In your client code:
const apiKey = process.env.API_KEY;
const debugMode = process.env.DEBUG === 'true';