vite-plugin-runtime-config

1.0.2 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Cannot find module 'vite-plugin-runtime-config' ↓

cause Package not installed.

fix

npm install --save-dev vite-plugin-runtime-config

error Error: Configuration option 'test' is not a valid key. ↓

cause Attempting to reference a placeholder like {{ test }} but VITE_ prefix is missing (env vars require VITE_ prefix).

fix

Use {{ VITE_test }} or define a correct environment variable with VITE_ prefix.

error Error: patch_runtime_config.js is missing. ↓

cause Build failed or plugin not applied correctly.

fix

Ensure runtimeConfig() is called in vite.config.ts plugins array and re-run 'npx vite build'.

Warnings

breaking 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. ↓

fix Update CI/CD to run 'node dist/patch_runtime_config.js' instead of 'node apply-config.js'.

deprecated 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'). ↓

fix Remove 'outDir' from runtimeConfig options and adjust paths accordingly.

gotcha 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. ↓

fix Ensure placeholders are formatted as '{{ VITE_VAR }}' or '{% VITE_RT_CONFIG %}'.

gotcha The plugin only processes 'index.html' by default. Custom HTML files are not patched unless explicitly specified via options. ↓

fix Set 'htmlFiles' option in runtimeConfig to include additional files, or run patch script on each file individually.

Install

npm install vite-plugin-runtime-config

yarn add vite-plugin-runtime-config

pnpm add vite-plugin-runtime-config

Imports

runtimeConfig

wrong

const runtimeConfig = require('vite-plugin-runtime-config')

correct

import runtimeConfig from 'vite-plugin-runtime-config'

Default export; ESM-only. CommonJS require will fail.

RuntimeConfigOptions

wrong

import { RuntimeConfigOptions } from 'vite-plugin-runtime-config'

correct

import type { RuntimeConfigOptions } from 'vite-plugin-runtime-config'

Type import; not a runtime value. Use import type to avoid bundler issues.

vite-plugin-runtime-config

wrong

import { runtimeConfig } from 'vite-plugin-runtime-config'

correct

import runtimeConfig from 'vite-plugin-runtime-config'

Default export only; named export 'runtimeConfig' does not exist.

Quickstart

Shows minimal setup: adding plugin to vite config, placeholder syntax, and build + post-build steps for production.

// vite.config.ts
import { defineConfig } from 'vite';
import runtimeConfig from 'vite-plugin-runtime-config';

export default defineConfig({
  plugins: [runtimeConfig()],
});

// index.html snippet
// Placeholder: {{ VITE_APP_TITLE }}
// Build: npx vite build
// Post-build: node dist/patch_runtime_config.js --in dist/index.html --out dist/index.html