vite-plugin-runtime

1.4.0 verified Mon Apr 27 auth: no javascript

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.

Common errors

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

cause Using a default import instead of a named import.

fix

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

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

cause 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').

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

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

fix

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

error Window.env is undefined at runtime ↓

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

Warnings

breaking Requires Node >=18; older Node versions will fail at install. ↓

fix Upgrade Node to version 18 or higher.

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

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

gotcha If `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.

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

deprecated The `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.

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

Install

npm install vite-plugin-runtime

yarn add vite-plugin-runtime

pnpm add vite-plugin-runtime

Imports

runtimeEnv
wrong
```
import runtimeEnv from 'vite-plugin-runtime'
```
correct
```
import { runtimeEnv } from 'vite-plugin-runtime'
```
Named export, not default. The function is named `runtimeEnv`, not `runtime`.

runtimeHtml

wrong

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

correct

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

ESM-only. CommonJS require is not supported.

VitePluginRuntime (type)

wrong

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

correct

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

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

Quickstart

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,
    }),
  ],
});