{"id":22652,"library":"vite-plugin-envsubst","title":"vite-plugin-envsubst","description":"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.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/abhiaagarwal/vite-plugin-envsubst","tags":["javascript","caddy","docker","kubernetes","nginx","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-envsubst","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-envsubst","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-envsubst","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin only works with Vite's build system.","package":"vite","optional":false}],"imports":[{"note":"ESM-only; no CommonJS support. Named export, not default.","wrong":"const envSubstPlugin = require('vite-plugin-envsubst')","symbol":"envSubstPlugin","correct":"import { envSubstPlugin } from 'vite-plugin-envsubst'"},{"note":"TypeScript users should use type import since EnvSubstPluginOptions is a type, not a value.","wrong":"import { EnvSubstPluginOptions } from 'vite-plugin-envsubst'","symbol":"EnvSubstPluginOptions","correct":"import type { EnvSubstPluginOptions } from 'vite-plugin-envsubst'"},{"note":"There is no default export; using default import will result in undefined.","wrong":"import envSubstPlugin from 'vite-plugin-envsubst'","symbol":"plugin default","correct":"import { envSubstPlugin } from 'vite-plugin-envsubst'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { envSubstPlugin } from 'vite-plugin-envsubst';\n\nexport default defineConfig({\n  plugins: [\n    envSubstPlugin({\n      globalObject: 'globalThis',\n      templateEngine: 'envsubst',\n      include: [/\\.([cm]?[jt]sx?)$/],\n      exclude: [/node_modules/],\n    }),\n  ],\n});\n\n// src/vite-env.d.ts must declare variables:\n/// <reference types=\"vite/client\" />\ninterface ImportMetaEnv {\n  readonly VITE_API_URL: string;\n}\ninterface ImportMeta {\n  readonly env: ImportMetaEnv;\n}\n\n// src/main.ts\nconst apiUrl = import.meta.env.VITE_API_URL;\nconsole.log(apiUrl);","lang":"typescript","description":"Configures Vite to transform declared import.meta.env variables into globalThis.env placeholders for runtime substitution."},"warnings":[{"fix":"Add interface ImportMetaEnv with readonly string fields for each variable in src/vite-env.d.ts","message":"Must declare environment variables in 'vite-env.d.ts' or they will NOT be transformed","severity":"gotcha","affected_versions":">=0.1.0"},{"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)","message":"Only variables matching Vite's envPrefix (default VITE_) are transformed by default","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use Caddy template engine or install envsubst in Docker image explicitly","message":"envsubst is not included in hardened nginx images like Chainguard's","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For dev server, provide actual env vars via .env files or command line. The plugin skips transform in dev mode.","message":"Plugin only runs during build; dev server uses native import.meta.env (placeholders are not replaced)","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Use import syntax and set module resolution to ESM or 'bundler' in tsconfig.json","message":"Importing from 'vite-plugin-envsubst' directly without ESM support can fail; no CommonJS require()","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add \"type\": \"module\" to package.json or use .mts extension for vite.config.ts","cause":"Using require() or ts-node without ESM enabled for this package","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Add interface ImportMetaEnv with readonly string fields in src/vite-env.d.ts","cause":"ImportMetaEnv interface not declared or empty in vite-env.d.ts","error":"Error: Plugin envSubstPlugin is missing required option 'vite-env.d.ts' or no variables found"},{"fix":"Use import { envSubstPlugin } from 'vite-plugin-envsubst'","cause":"Wrong import style (default import instead of named import)","error":"TypeError: envSubstPlugin is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}