vite-plugin-runtime-env

1.0.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: Cannot find module 'vite-plugin-runtime-env' ↓

cause Package not installed or not in node_modules.

fix

Run 'npm install --save-dev vite-plugin-runtime-env'

error TypeError: runtimeEnv is not a function ↓

cause Default import mismatch; using require in ESM context or incorrect import style.

fix

Use 'import runtimeEnv from 'vite-plugin-runtime-env'' (ESM).

error [plugin:vite-plugin-runtime-env] Unknown substitution syntax ↓

cause Invalid value for substitutionSyntax option.

fix

Use one of 'dollar-basic', 'dollar-curly', or 'handlebars'.

error ReferenceError: import.meta is not defined ↓

cause Code running outside of a module context (e.g., Node.js script).

fix

Only use import.meta.env in browser/ESM context; the plugin only applies to Vite builds.

error Error: The environment variable VITE_XXX is not defined ↓

cause Variable was not found in process.env at build time or deployment placeholder not substituted.

fix

Define the variable in the deployment environment or set substitution syntax correctly.

Warnings

breaking v1.0.0: First stable release – no longer considered experimental. ↓

fix Update to v1.0.0 or later; check for API stability.

deprecated Pre-v1.0.0 versions used an unstable API that may change in future releases. ↓

fix Use v1.0.0+ for a stable API.

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

fix Ensure all runtime environment variables are prefixed with VITE_ and included in the plugin's scope.

gotcha The plugin does not actually substitute environment variables at runtime; it only replaces them with placeholders that require external substitution during deployment. ↓

fix Use a tool like envsubst or npx envsub to replace placeholders when deploying.

deprecated The option 'substitutionSyntax' with value 'handlebars' may be deprecated in future if broader syntax support is added. ↓

fix Monitor release notes; consider using 'dollar-curly' as default.

Install

npm install vite-plugin-runtime-env

yarn add vite-plugin-runtime-env

pnpm add vite-plugin-runtime-env

Imports

runtimeEnv

wrong

const runtimeEnv = require('vite-plugin-runtime-env')

correct

import runtimeEnv from 'vite-plugin-runtime-env'

Package is ESM-only; default export is the plugin function.

runtimeEnv ({...})
wrong
```
runtimeEnv.variableName = 'window.myEnv'
```
correct
```
runtimeEnv({ variableName: 'window.myEnv' })
```
Configuration is passed as an options object, not by modifying the imported function.
RuntimeEnvOptions (TypeScript type)
```
import type { RuntimeEnvOptions } from 'vite-plugin-runtime-env'
```
TypeScript users can import the options interface for type-checking.

Quickstart

Configures vite-plugin-runtime-env to replace import.meta.env with window.env references and inject placeholders in index.html.

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

export default defineConfig({
  plugins: [
    runtimeEnv({
      variableName: 'window.env',
      injectHtml: true,
      substitutionSyntax: 'dollar-curly',
    }),
  ],
});

// In your application code (e.g., src/App.ts):
const apiUrl = import.meta.env.VITE_API_URL;
// After build, the above becomes window.env.VITE_API_URL,
// and index.html contains a script: window.env = { VITE_API_URL: '${VITE_API_URL}' };
// Substitute at deploy time: npx envsub dist/index.html