Registry / web-framework / vite-plugin-html-config

vite-plugin-html-config

library2.0.2jsnpmunverified

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.

web-framework devops

npm install vite-plugin-html-config

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-HTML-C

vite-plugin-html-config

web-frameworkjavascriptv2.0.2

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.

htmlPlugin

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

✗ const htmlPlugin = require('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)

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

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

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

Debug

Known issues

breakingVite 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).

affects: >=2.0.0 <2.0.0

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

affects: >=2.0.0

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

affects: all

gotchaString-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' }.

affects: all

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

affects: 2.0.2

Errors

Common errors & fixes

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

Plugin not installed or npm install failed.

fix

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

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

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

TypeError: htmlPlugin is not a function

Using a named import instead of default import.

fix

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

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

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.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

viterequiredPeer dependency: requires Vite >=5.0.0 to function (transformIndexHtml hook).

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ahwgs/vite-plugin-html-config ↗

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