Registry / devops / vite-plugin-runtime-env

vite-plugin-runtime-env

library1.0.0jsnpmunverified

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.

devops

npm install vite-plugin-runtime-env

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-RUNTIM

vite-plugin-runtime-env

devopsjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

runtimeEnv

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

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

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

runtimeEnv ({...})

✓ runtimeEnv({ variableName: 'window.myEnv' })

✗ 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.

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

Debug

Known issues

breakingv1.0.0: First stable release – no longer considered experimental.

fix

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

affects: <1.0.0

deprecatedPre-v1.0.0 versions used an unstable API that may change in future releases.

fix

Use v1.0.0+ for a stable API.

affects: <1.0.0

gotchaVariables 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.

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

deprecatedThe 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

Package not installed or not in node_modules.

fix

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

TypeError: runtimeEnv is not a function

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

fix

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

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

Invalid value for substitutionSyntax option.

fix

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

ReferenceError: import.meta is not defined

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: The environment variable VITE_XXX is not defined

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.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

viterequiredPeer dependency required for plugin integration

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/micha149/vite-plugin-runtime-env ↗

packagehttps://www.npmjs.com/package/vite-plugin-runtime-env ↗

homepagehttps://www.vite-plugin-runtime-env.dev ↗