vite-plugin-html-config

2.0.2 verified Mon Apr 27 auth: no javascript

A Vite plugin (v2.0.2) for injecting HTML tags (meta, link, script, style) into the index.html at build time. It uses Vite's transformIndexHtml hook and supports configurable head/body scripts with both string and object-based attributes. Unlike raw transformIndexHtml hooks, it provides a declarative, environment-aware API for conditionally adding tags. Requires Vite >=5.0.0. Currently in active development with support for Vite 3–5.

Common errors

error Failed to resolve import "vite-plugin-html-config" from "vite.config.ts". Does the file exist? ↓

cause Plugin not installed or npm install failed.

fix

Run: npm install vite-plugin-html-config -D (or yarn/pnpm equivalent).

error Error: The plugin 'vite-plugin-html-config' requires Vite >=5.0.0 but the current Vite version is 4.x.x. ↓

cause Vite version mismatch: plugin v2.x requires Vite 5+.

fix

Upgrade Vite to >=5.0.0, or downgrade plugin to v1.x (npm install vite-plugin-html-config@1).

error TypeError: htmlPlugin is not a function ↓

cause Using a named import instead of default import.

fix

Change import to: import htmlPlugin from 'vite-plugin-html-config' (default import).

error Unexpected token 'export' (in vite.config.js when using require) ↓

cause Using CommonJS require() for an ESM-only package.

fix

Use ESM syntax: import htmlPlugin from 'vite-plugin-html-config'. If your config is CJS, rename to .mjs or set type: module in package.json.

Warnings

breaking Vite 5+ peer dependency required. Plugin v2.x will not work with Vite 2.x or 3.x due to API changes in transformIndexHtml. ↓

fix Upgrade to Vite >=5.0.0 or use v1.x for older Vite (v2/v3).

deprecated Plugin options 'title' and 'favicon' may be deprecated in future versions; use 'metas' with <title> and <link> tags instead. ↓

fix Migrate to explicit meta/link tags for title and favicon to avoid removal.

gotcha Order of scripts: 'headScripts' inserts before </head>, 'preHeadScripts' inserts after <head> but before other head scripts, 'scripts' inserts before </body>. Misunderstanding order leads to incorrect script positioning. ↓

fix Use 'preHeadScripts' for scripts that must run before other head scripts (e.g., polyfills), 'headScripts' for general head scripts, 'scripts' for body-end scripts.

gotcha String-based scripts are not automatically wrapped in a script tag; they are injected as literal HTML. If you pass a plain string, it is inserted as raw HTML content inside a <script> tag. To include external src, use object syntax. ↓

fix For external scripts, use { src: 'url' } object; for inline code, use a string or { content: 'code' }.

gotcha TypeScript users: the exported type name may not be 'HtmlConfigOptions' in v2.0.2; check the actual exported type from the package if you need strict typing. ↓

fix Use 'typeof htmlPlugin extends (opts: infer T) => any ? T : never' or inspect the .d.ts file in node_modules.

Install

npm install vite-plugin-html-config

yarn add vite-plugin-html-config

pnpm add vite-plugin-html-config

Imports

htmlPlugin
wrong
```
const htmlPlugin = require('vite-plugin-html-config')
```
correct
```
import htmlPlugin from 'vite-plugin-html-config'
```
ESM-only; no CommonJS export. Package type is not set, but Vite typically expects ESM.

vite-plugin-html-config (default export)

wrong

import { htmlPlugin } from 'vite-plugin-html-config'

correct

import htmlPlugin from 'vite-plugin-html-config'

Only a default export exists; named import will fail.

htmlPlugin options type
```
import type { HtmlConfigOptions } from 'vite-plugin-html-config'
```
Types are bundled, but the type name may not be exported explicitly in older versions. Check v2.0.2 types.

Quickstart

Demonstrates minimal configuration with all supported HTML injection options: title, favicon, metas, links, head/body scripts, and inline style.

// vite.config.js
import htmlPlugin from 'vite-plugin-html-config';

export default defineConfig({
  plugins: [
    htmlPlugin({
      title: 'My App',
      favicon: '/favicon.ico',
      metas: [
        { name: 'keywords', content: 'vite,plugin,html' },
        { name: 'description', content: 'A Vite plugin for HTML config' }
      ],
      links: [
        { rel: 'stylesheet', href: '/src/style.css' }
      ],
      headScripts: [
        { src: 'https://example.com/analytics.js', async: true }
      ],
      scripts: [
        'console.log("body script")'
      ],
      style: 'body { background: #f0f0f0; }'
    })
  ]
});