vite-envs

4.6.2 verified Mon Apr 27 auth: no javascript

Vite plugin (v4.6.2, actively maintained) that enables dynamic injection of environment variables at container startup rather than build time. Designed for Dockerized Vite apps, it generates a shell script during build that populates import.meta.env and index.html placeholders (e.g., %FOO%) at runtime. Unlike standard Vite which requires rebuilding for env changes, vite-envs allows deploying a single Docker image configurable via --env flags. Supports type-safe imports with hot reload, optional EJS in HTML, and explicit variable declaration. Does not require the VITE_ prefix.

Common errors

error Cannot find module 'vite-envs' or its corresponding type declarations. ↓

cause Package not installed or TypeScript config missing module resolution for vite-envs.

fix

npm install vite-envs --save-dev && ensure tsconfig.json includes 'node' in moduleResolution or 'moduleResolution': 'bundler'.

error TypeError: viteEnvs is not a function ↓

cause Importing viteEnvs incorrectly (e.g., as default export when using named import syntax).

fix

Use 'import { viteEnvs } from 'vite-envs'; or 'import viteEnvs from 'vite-envs';'

error env variable FOO is not being injected at runtime ↓

cause FOO not listed in .env file or plugin declaration, so vite-envs.sh does not include it.

fix

Add FOO to your .env file (even with a dummy value) or use the declaration option in viteEnvs().

Warnings

breaking vite-envs v4 generates a shell script (vite-envs.sh) rather than directly modifying the bundle. Previous versions (<4) used a different injection mechanism. ↓

fix Update Dockerfile to run ./vite-envs.sh before starting server (see README).

gotcha Environment variables not declared in .env (or .env.declaration) will NOT be injected at runtime, even if present in the host environment. This is a security feature. ↓

fix List all expected variables in a .env file (or use the declaration option in vite.config.ts).

gotcha The VITE_ prefix is NOT required, but if you omit it, you must ensure the variable is declared. Mixing VITE_ and non-VITE_ variables can cause confusion. ↓

fix Use explicit declaration for all env vars to avoid surprises.

deprecated In v4.6.0+, you can overwrite the global name via the plugin option nameOfTheGlobalOld. This may change in future versions. ↓

fix Avoid relying on internal global names; use the default behavior.

Install

npm install vite-envs

yarn add vite-envs

pnpm add vite-envs

Imports

viteEnvs

wrong

const viteEnvs = require('vite-envs')

correct

import { viteEnvs } from 'vite-envs'

ESM-only; CJS require() fails in modern Vite configs.

default import
wrong
```
import { default } from 'vite-envs'
```
correct
```
import viteEnvs from 'vite-envs'
```
viteEnvs is also the default export; both syntaxes work.
defineEnvVars
```
import { defineEnvVars } from 'vite-envs'
```
Utility for type-safe env variable declarations; available since v4.

Quickstart

Minimal Vite config using viteEnvs plugin. Shows declaration, .env fallback, and runtime access via import.meta.env.

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteEnvs } from 'vite-envs';

export default defineConfig({
  plugins: [
    react(),
    viteEnvs({
      // Declare env vars (optional, but required for type generation)
      declaration: {
        FOO: 'VITE_FOO', // default value
        BAR: 'default_bar'
      }
    })
  ]
});

// .env file (if not using declaration)
VITE_FOO=hello
BAR=world

// In your TypeScript code:
console.log(import.meta.env.FOO); // 'hello' at runtime
console.log(import.meta.env.BAR); // 'world'

// Docker usage:
// docker run --env FOO="xyz" --env BAR="abc" my-image