Registry / devops / vite-plugin-runtime

vite-plugin-runtime

library1.4.0jsnpmunverified

A Vite plugin that replaces `import.meta.env.VITE_*` with `window.env.*` at build time for flexible runtime environment variable injection. Current stable version is 1.4.0 (July 2024). Releases are active with a new minor/patch version every few months, adding features like `envsubstTemplate` and `injectHtml`. Key differentiators: eliminates the VITE_ prefix requirement, generates runtime env.js files, supports type generation, and can inject HTML scripts. Requires Node >=18 and any version of Vite. Peer dependency on Vite is required.

devops web-framework

npm install vite-plugin-runtime

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-RUNTIM

vite-plugin-runtime

devopsjavascriptv1.4.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'

✗ import runtimeEnv from 'vite-plugin-runtime'

Named export, not default. The function is named `runtimeEnv`, not `runtime`.

runtimeHtml

✓ import { runtimeHtml } from 'vite-plugin-runtime'

✗ const { runtimeHtml } = require('vite-plugin-runtime')

ESM-only. CommonJS require is not supported.

VitePluginRuntime (type)

✓ import type { VitePluginRuntimeOptions } from 'vite-plugin-runtime'

✗ import { VitePluginRuntimeOptions } from 'vite-plugin-runtime'

Options type is exported as a type, not a value. Use `import type` in TypeScript.

Configures vite-plugin-runtime with the runtimeEnv plugin, setting the runtime object name to 'env', enabling HTML injection and type generation.

// vite.config.ts import { defineConfig } from 'vite'; import { runtimeEnv } from 'vite-plugin-runtime'; export default defineConfig({ plugins: [ runtimeEnv({ name: 'env', injectHtml: true, generateTypes: true, generatedTypesPath: () => './src', envsubstTemplate: false, }), ], });

Debug

Known issues

breakingRequires Node >=18; older Node versions will fail at install.

fix

Upgrade Node to version 18 or higher.

affects: >=1.0.0

breakingThe plugin only works in ESM environments; CommonJS import (require) will throw an error.

fix

Use ESM imports: `import { runtimeEnv } from 'vite-plugin-runtime'`.

affects: >=1.0.0

gotchaIf `injectHtml` is false, you must manually include `/env.js` or the runtime variables will not be available.

fix

Either leave `injectHtml: true` or add a `<script>` tag loading `/env.js` in your HTML file.

affects: >=1.0.0

gotchaThe default `name` is `env`, so runtime variables are accessed as `window.env.VARIABLE` instead of `import.meta.env.VITE_VARIABLE`.

fix

Update your code to use `window.env.VARIABLE` or set a custom `name` option.

affects: >=1.0.0

deprecatedThe `envsubstTemplate` option defaults to `false` and is not intended for production use; it's for generating a template for environment variable substitution.

fix

Only enable `envsubstTemplate` if you specifically need to create an envsubst template file.

affects: >=1.4.0

gotchaIf you have multiple runtimeEnv plugin instances with different names, the last one's configuration may override previous ones due to Vite plugin order.

fix

Use only one runtimeEnv plugin instance, or ensure plugin ordering is correct.

affects: >=1.0.0

Errors

Common errors & fixes

Error: 'runtimeEnv' is not exported from 'vite-plugin-runtime'

Using a default import instead of a named import.

fix

Change to `import { runtimeEnv } from 'vite-plugin-runtime'`.

TypeError: require(...) is not a function

Trying to use CommonJS require with this ESM-only package.

fix

Switch to ESM imports or use a dynamic import: `const { runtimeEnv } = await import('vite-plugin-runtime')`.

Cannot find module 'vite-plugin-runtime' or its corresponding type declarations.

Missing peer dependency 'vite' or not installed as devDependency.

fix

Run `npm install --save-dev vite vite-plugin-runtime`.

Window.env is undefined at runtime

The `injectHtml` option is set to `false` and the env.js script is not manually loaded.

fix

Set `injectHtml: true` or manually include `<script src='/env.js'></script>` in your HTML file.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

viterequiredRequired as a peer dependency; the plugin hooks into Vite's build process.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/flexbase-eng/vite-plugin-runtime ↗

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