{"id":22820,"library":"vite-plugin-runtime-config","title":"vite-plugin-runtime-config","description":"A Vite plugin (v1.0.2) enabling runtime configuration for static builds. Unlike Vite's built-in env variables that are baked at build time, this plugin allows dynamic replacement of config placeholders (e.g., {{ VITE_X }}) in index.html via a generated script (patch_runtime_config.js). Supports development mode (auto-replacement from Vite env) and production mode (post-build script execution). Requires Vite ^3.1.0 and Vitest >0.23.2 <1.0 as peer dependencies. Suitable for projects served by external webservers without SSR.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/Viva-con-Agua/vite-plugin-runtime-config","tags":["javascript","front-end","configuration","vite-plugin"],"install":[{"cmd":"npm install vite-plugin-runtime-config","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-runtime-config","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-runtime-config","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin requires Vite >=3.1.0","package":"vite","optional":false},{"reason":"Peer dependency for testing; required only for development","package":"vitest","optional":true}],"imports":[{"note":"Default export; ESM-only. CommonJS require will fail.","wrong":"const runtimeConfig = require('vite-plugin-runtime-config')","symbol":"runtimeConfig","correct":"import runtimeConfig from 'vite-plugin-runtime-config'"},{"note":"Type import; not a runtime value. Use import type to avoid bundler issues.","wrong":"import { RuntimeConfigOptions } from 'vite-plugin-runtime-config'","symbol":"RuntimeConfigOptions","correct":"import type { RuntimeConfigOptions } from 'vite-plugin-runtime-config'"},{"note":"Default export only; named export 'runtimeConfig' does not exist.","wrong":"import { runtimeConfig } from 'vite-plugin-runtime-config'","symbol":"vite-plugin-runtime-config","correct":"import runtimeConfig from 'vite-plugin-runtime-config'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport runtimeConfig from 'vite-plugin-runtime-config';\n\nexport default defineConfig({\n  plugins: [runtimeConfig()],\n});\n\n// index.html snippet\n// Placeholder: {{ VITE_APP_TITLE }}\n// Build: npx vite build\n// Post-build: node dist/patch_runtime_config.js --in dist/index.html --out dist/index.html","lang":"typescript","description":"Shows minimal setup: adding plugin to vite config, placeholder syntax, and build + post-build steps for production."},"warnings":[{"fix":"Update CI/CD to run 'node dist/patch_runtime_config.js' instead of 'node apply-config.js'.","message":"Node script location mismatch: In versions prior to 1.0.0, the patch script was named 'apply-config.js' and located at root of output. Since v1.0.0, it is 'patch_runtime_config.js' in the dist folder.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Remove 'outDir' from runtimeConfig options and adjust paths accordingly.","message":"The 'outDir' option is deprecated in v1.0.0+. The patch script is always placed in the Vite output directory (configured by build.outDir, default 'dist').","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Ensure placeholders are formatted as '{{ VITE_VAR }}' or '{% VITE_RT_CONFIG %}'.","message":"Placeholder syntax must match exactly: use double curly braces with leading/trailing spaces ({{ VITE_X }}) or {% VITE_RT_CONFIG %}. Single braces or missing spaces will not be replaced.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set 'htmlFiles' option in runtimeConfig to include additional files, or run patch script on each file individually.","message":"The plugin only processes 'index.html' by default. Custom HTML files are not patched unless explicitly specified via options.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"npm install --save-dev vite-plugin-runtime-config","cause":"Package not installed.","error":"Cannot find module 'vite-plugin-runtime-config'"},{"fix":"Use {{ VITE_test }} or define a correct environment variable with VITE_ prefix.","cause":"Attempting to reference a placeholder like {{ test }} but VITE_ prefix is missing (env vars require VITE_ prefix).","error":"Error: Configuration option 'test' is not a valid key."},{"fix":"Ensure runtimeConfig() is called in vite.config.ts plugins array and re-run 'npx vite build'.","cause":"Build failed or plugin not applied correctly.","error":"Error: patch_runtime_config.js is missing."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}