vite-plugin-html-variables

1.0.4 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables using environment variables and custom variables in HTML files by replacing placeholders like {{VAR}} with actual values at build time. Version 1.0.4 is the current stable release, updated irregularly. Key differentiators include support for custom prefixes/suffixes, the ability to exclude environment variables, and TypeScript definitions. It is minimal and focused on a single task, unlike heavier solutions like @vitejs/plugin-legacy or custom middleware.

Common errors

error Error: Cannot find module 'vite-plugin-html-variables' ↓

cause Package not installed or incorrect import path.

fix

Install with: npm i -D vite-plugin-html-variables

error Uncaught ReferenceError: VITE_APP_TITLE is not defined (in HTML) ↓

cause Variable not passed via env or variables object, or excludeEnvVariables set to true.

fix

Ensure VITE_ prefix is used in .env or add variable to variables config.

error TypeError: htmlVariables is not a function ↓

cause Incorrect import (named instead of default).

fix

Use: import htmlVariables from 'vite-plugin-html-variables'

Warnings

gotcha Environment variables not prefixed with VITE_ must be explicitly passed via the `variables` config option, otherwise they are not exposed to the HTML. ↓

fix Use VITE_ prefix for env vars or add them to the `variables` object.

gotcha The plugin replaces placeholders in HTML files only during build (vite build) and not in dev server (vite dev). Changes to variables may require a full server restart. ↓

fix Restart the dev server after modifying .env or variables config.

gotcha If `excludeEnvVariables` is set to true, VITE_ prefixed env variables will not be available in the HTML, even if they are in the environment. ↓

fix Set excludeEnvVariables: false or use the variables object to include specific vars.

breaking Previous versions (before 1.0.0) used different default prefix/suffix or API. Check changelog for migration. ↓

fix Upgrade to latest version and update config accordingly (default prefix='{{', suffix='}}').

Install

npm install vite-plugin-html-variables

yarn add vite-plugin-html-variables

pnpm add vite-plugin-html-variables

Imports

htmlVariables

wrong

const htmlVariables = require('vite-plugin-html-variables')

correct

import htmlVariables from 'vite-plugin-html-variables'

Default ESM export. CJS require is not supported due to Vite's ESM-only plugin ecosystem.

default export (factory function)
wrong
```
import { htmlVariables } from 'vite-plugin-html-variables'
```
correct
```
import htmlVariables from 'vite-plugin-html-variables'
```
This is a default export, not a named export. Named import will result in undefined.
HtmlVariablesOptions (TypeScript type)
wrong
```
import { HtmlVariablesOptions } from 'vite-plugin-html-variables'
```
correct
```
import type { HtmlVariablesOptions } from 'vite-plugin-html-variables'
```
The type is only available as a TypeScript type export, not a runtime value. Use 'import type' or ignore if not using TS.

Quickstart

Shows basic usage of vite-plugin-html-variables with custom variables and env variable inclusion.

// vite.config.ts or vite.config.js
import { defineConfig } from 'vite';
import htmlVariables from 'vite-plugin-html-variables';

export default defineConfig({
  plugins: [
    htmlVariables({
      prefix: '{{',
      suffix: '}}',
      variables: { MY_VAR: 'Hello World' },
      excludeEnvVariables: false,
    }),
  ],
});

// .env file (optional, if not using variables object)
VITE_APP_TITLE=My App