vite-plugin-env-config

2.0.1 verified Mon Apr 27 auth: no javascript

Vite plugin that allows setting Vite config options via environment variables at build time. Current version 2.0.1, stable release cadence with occasional patches. Key differentiator: enables dynamic config overrides without modifying vite.config files, using a configurable prefix (default VITECONFIG_) and separator for nested object keys. Supports JSON-like value parsing with string fallback. Simple API, lightweight, TypeScript types included.

Common errors

error Cannot find module 'vite-plugin-env-config' ↓

cause Package not installed or not in dependencies

fix

npm install vite-plugin-env-config --save-dev (or pnpm/yarn equivalent)

error Error: The plugin 'vite-plugin-env-config' is not compatible with Vite 5 ↓

cause Plugin version may be outdated or not updated for Vite 5

fix

Check compatibility; currently v2.0.1 works with Vite 4.x. For Vite 5, look for an updated version or alternative plugin.

error TypeError: envConfig is not a function ↓

cause Possibly using a wrong import (default vs named).

fix

Use named import: import { envConfig } from 'vite-plugin-env-config'

Warnings

breaking Dropped support for Node 12 in v2.0.0 ↓

fix Upgrade to Node 14.13.1 or later, or stay on v1.x if you must use Node 12

gotcha Value parsing uses JSON.parse; non-JSON values become strings. Booleans and numbers must be valid JSON (e.g., true, false, 42). Undefined/unquoted strings cause parse errors. ↓

fix Use JSON-compatible values: `true`, `false`, `"string"`, `123`. For string values that are not JSON, they remain strings.

gotcha Cannot set array items; only object properties are supported. Environment variable keys with numeric indices will be treated as object keys. ↓

fix Use a different approach for arrays (e.g., set as a JSON string and parse manually).

gotcha Environment variable charset is limited to uppercase A-Z, underscore, and numbers. The prefix and property path must use underscore as separator; double underscore `__` is reserved for literal underscore in keys. ↓

fix Use single underscore for path separator. If a property name contains underscore, double it (e.g., `VITECONFIG_foo__bar=1` sets `{foo: {bar: 1}}`).

Install

npm install vite-plugin-env-config

yarn add vite-plugin-env-config

pnpm add vite-plugin-env-config

Imports

envConfig

wrong

const { envConfig } = require('vite-plugin-env-config')

correct

import { envConfig } from 'vite-plugin-env-config'

ESM-only package; requires Node >=14.13.1

Quickstart

Shows basic setup and usage with an example environment variable override

// vite.config.ts
import { defineConfig } from 'vite';
import { envConfig } from 'vite-plugin-env-config';

export default defineConfig({
  plugins: [
    envConfig({
      prefix: 'VITECONFIG_',
      separator: '_'
    })
  ]
});

// Then run:
// VITECONFIG_build_minify=false vite build
// This overrides build.minify to false