{"id":22824,"library":"vite-plugin-runtime-env","title":"vite-plugin-runtime-env","description":"Vite plugin that injects environment variables at runtime instead of build time, enabling adherence to 12-factor app principles. Current stable version is v1.0.0, released as first stable after a long period in pre-release. It replaces import.meta.env references with window.env lookups and inserts placeholder variables in index.html for substitution during deployment using tools like envsubst. Key differentiators: supports multiple substitution syntaxes (dollar-basic, dollar-curly, handlebars), optionally ignores certain variables for build-time replacement, and allows custom variable names. Requires Vite as a peer dependency.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/micha149/vite-plugin-runtime-env","tags":["javascript","docker","environment","12-factor","vite","dot-env","vite-plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-runtime-env","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-runtime-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-runtime-env","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for plugin integration","package":"vite","optional":false}],"imports":[{"note":"Package is ESM-only; default export is the plugin function.","wrong":"const runtimeEnv = require('vite-plugin-runtime-env')","symbol":"runtimeEnv","correct":"import runtimeEnv from 'vite-plugin-runtime-env'"},{"note":"Configuration is passed as an options object, not by modifying the imported function.","wrong":"runtimeEnv.variableName = 'window.myEnv'","symbol":"runtimeEnv ({...})","correct":"runtimeEnv({ variableName: 'window.myEnv' })"},{"note":"TypeScript users can import the options interface for type-checking.","wrong":"","symbol":"RuntimeEnvOptions (TypeScript type)","correct":"import type { RuntimeEnvOptions } from 'vite-plugin-runtime-env'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport runtimeEnv from 'vite-plugin-runtime-env';\n\nexport default defineConfig({\n  plugins: [\n    runtimeEnv({\n      variableName: 'window.env',\n      injectHtml: true,\n      substitutionSyntax: 'dollar-curly',\n    }),\n  ],\n});\n\n// In your application code (e.g., src/App.ts):\nconst apiUrl = import.meta.env.VITE_API_URL;\n// After build, the above becomes window.env.VITE_API_URL,\n// and index.html contains a script: window.env = { VITE_API_URL: '${VITE_API_URL}' };\n// Substitute at deploy time: npx envsub dist/index.html","lang":"typescript","description":"Configures vite-plugin-runtime-env to replace import.meta.env with window.env references and inject placeholders in index.html."},"warnings":[{"fix":"Update to v1.0.0 or later; check for API stability.","message":"v1.0.0: First stable release – no longer considered experimental.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use v1.0.0+ for a stable API.","message":"Pre-v1.0.0 versions used an unstable API that may change in future releases.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Ensure all runtime environment variables are prefixed with VITE_ and included in the plugin's scope.","message":"Variables not included in the plugin will remain as import.meta.env references and cause runtime errors if not replaced by Vite's build-time handling.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use a tool like envsubst or npx envsub to replace placeholders when deploying.","message":"The plugin does not actually substitute environment variables at runtime; it only replaces them with placeholders that require external substitution during deployment.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Monitor release notes; consider using 'dollar-curly' as default.","message":"The option 'substitutionSyntax' with value 'handlebars' may be deprecated in future if broader syntax support is added.","severity":"deprecated","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run 'npm install --save-dev vite-plugin-runtime-env'","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'vite-plugin-runtime-env'"},{"fix":"Use 'import runtimeEnv from 'vite-plugin-runtime-env'' (ESM).","cause":"Default import mismatch; using require in ESM context or incorrect import style.","error":"TypeError: runtimeEnv is not a function"},{"fix":"Use one of 'dollar-basic', 'dollar-curly', or 'handlebars'.","cause":"Invalid value for substitutionSyntax option.","error":"[plugin:vite-plugin-runtime-env] Unknown substitution syntax"},{"fix":"Only use import.meta.env in browser/ESM context; the plugin only applies to Vite builds.","cause":"Code running outside of a module context (e.g., Node.js script).","error":"ReferenceError: import.meta is not defined"},{"fix":"Define the variable in the deployment environment or set substitution syntax correctly.","cause":"Variable was not found in process.env at build time or deployment placeholder not substituted.","error":"Error: The environment variable VITE_XXX is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}