Registry / devops / vite-plugin-envsubst

vite-plugin-envsubst

library0.3.0jsnpmunverified

A Vite plugin that transforms import.meta.env references to globalThis.env placeholders for runtime substitution via envsubst or Caddy's templating engine. Current stable version 0.3.0. Released in April 2025. Solves the problem of environment-specific builds by deferring variable injection to runtime, suitable for Docker/Kubernetes deployments. Key differentiators: only transforms declared variables from vite-env.d.ts, respects Vite's envPrefix, supports both envsubst and Caddy template syntax, and uses sourcemap-preserving transforms with a single runtime dependency (rolldown-string). Unlike other env injection plugins, it enables true build-once-deploy-anywhere without build-time environment knowledge.

devops

npm install vite-plugin-envsubst

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-ENVSUB

vite-plugin-envsubst

devopsjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

envSubstPlugin

✓ import { envSubstPlugin } from 'vite-plugin-envsubst'

✗ const envSubstPlugin = require('vite-plugin-envsubst')

ESM-only; no CommonJS support. Named export, not default.

EnvSubstPluginOptions

✓ import type { EnvSubstPluginOptions } from 'vite-plugin-envsubst'

✗ import { EnvSubstPluginOptions } from 'vite-plugin-envsubst'

TypeScript users should use type import since EnvSubstPluginOptions is a type, not a value.

plugin default

✓ import { envSubstPlugin } from 'vite-plugin-envsubst'

✗ import envSubstPlugin from 'vite-plugin-envsubst'

There is no default export; using default import will result in undefined.

Configures Vite to transform declared import.meta.env variables into globalThis.env placeholders for runtime substitution.

// vite.config.ts import { defineConfig } from 'vite'; import { envSubstPlugin } from 'vite-plugin-envsubst'; export default defineConfig({ plugins: [ envSubstPlugin({ globalObject: 'globalThis', templateEngine: 'envsubst', include: [/\.([cm]?[jt]sx?)$/], exclude: [/node_modules/], }), ], }); // src/vite-env.d.ts must declare variables: /// <reference types="vite/client" /> interface ImportMetaEnv { readonly VITE_API_URL: string; } interface ImportMeta { readonly env: ImportMetaEnv; } // src/main.ts const apiUrl = import.meta.env.VITE_API_URL; console.log(apiUrl);

Debug

Known issues

gotchaMust declare environment variables in 'vite-env.d.ts' or they will NOT be transformed

fix

Add interface ImportMetaEnv with readonly string fields for each variable in src/vite-env.d.ts

affects: >=0.1.0

gotchaOnly variables matching Vite's envPrefix (default VITE_) are transformed by default

fix

Set envPrefix in Vite config to include non-VITE_ variables or declare them in vite-env.d.ts (still only VITE_ transformed unless prefix changed)

affects: >=0.1.0

gotchaenvsubst is not included in hardened nginx images like Chainguard's

fix

Use Caddy template engine or install envsubst in Docker image explicitly

affects: >=0.1.0

breakingPlugin only runs during build; dev server uses native import.meta.env (placeholders are not replaced)

fix

For dev server, provide actual env vars via .env files or command line. The plugin skips transform in dev mode.

affects: >=0.1.0

gotchaImporting from 'vite-plugin-envsubst' directly without ESM support can fail; no CommonJS require()

fix

Use import syntax and set module resolution to ESM or 'bundler' in tsconfig.json

affects: >=0.1.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Using require() or ts-node without ESM enabled for this package

fix

Add "type": "module" to package.json or use .mts extension for vite.config.ts

Error: Plugin envSubstPlugin is missing required option 'vite-env.d.ts' or no variables found

ImportMetaEnv interface not declared or empty in vite-env.d.ts

fix

Add interface ImportMetaEnv with readonly string fields in src/vite-env.d.ts

TypeError: envSubstPlugin is not a function

Wrong import style (default import instead of named import)

fix

Use import { envSubstPlugin } from 'vite-plugin-envsubst'

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

viterequiredPeer dependency; the plugin only works with Vite's build system.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/abhiaagarwal/vite-plugin-envsubst ↗

packagehttps://www.npmjs.com/package/vite-plugin-envsubst ↗