vite-plugin-html-injection

1.5.2 verified Mon Apr 27 auth: no javascript

Vite plugin (v1.5.2) for injecting HTML, JS, and CSS code snippets into index.html at the head or body, with support for different build modes (dev/prod), HMR during development, and strongly typed configuration. Unlike similar tools that require placeholder tags, this plugin injects content by file path and position. Designed for managing third-party scripts, meta tags, and analytics without cluttering index.html. Requires Vite >= 4.0.0, ships TypeScript types, and is actively maintained.

Common errors

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

cause The package is not installed correctly or is missing from node_modules.

fix

Run npm install vite-plugin-html-injection --save-dev or pnpm add vite-plugin-html-injection -D.

error TypeError: htmlInjectionPlugin is not a function ↓

cause The import is wrong; likely using default import instead of named import.

fix

Use import { htmlInjectionPlugin } from 'vite-plugin-html-injection' (curly braces).

error Property 'htmlInjectionPlugin' does not exist on type 'typeof import("vite-plugin-html-injection")' ↓

cause TypeScript error from using wrong import syntax or mistyping the export name.

fix

Ensure the import statement is import { htmlInjectionPlugin } from 'vite-plugin-html-injection' and verify the package version includes that export.

error ENOENT: no such file or directory, open '/absolute/path/to/injection.html' ↓

cause The `path` in the injection config is absolute or incorrectly relative.

fix

Use a path relative to the project root, e.g., './src/injections/og.html', not an absolute path.

Warnings

breaking In v1.0.0 the export name changed from `vitePluginHtmlInjection` to `htmlInjectionPlugin`. Old imports will break. ↓

fix Use `import { htmlInjectionPlugin } from 'vite-plugin-html-injection'` instead.

gotcha The `order` option defaults to `'post'` if not specified, meaning the injection runs after Vite's built-in HTML transform. If you need to use `%ENV%` placeholders in your injected files, set `order: 'pre'`. ↓

fix Add `order: 'pre'` to the config if environment variable substitution is needed in injected files.

gotcha The injected file path is relative to the Vite project root (where `vite.config.js` is located), not relative to the config file. Using absolute paths is not recommended. ↓

fix Place injection files inside the project root (e.g., `./src/injections/`) and reference them with relative paths starting with `./` or `../`.

deprecated The `type` field with value `'js'` or `'css'` causes the plugin to wrap content in `<script>` or `<style>` tags. This may not work as expected if the file already contains those tags. Consider using `'raw'` and manually wrapping. ↓

fix Use `type: 'raw'` and include the `<script>` or `<style>` tags in the file yourself if you need more control.

gotcha The plugin does not validate that the injected code is syntactically correct or that JavaScript files are valid. Errors may only surface at runtime. ↓

fix Test injection files manually before relying on them.

Install

npm install vite-plugin-html-injection

yarn add vite-plugin-html-injection

pnpm add vite-plugin-html-injection

Imports

htmlInjectionPlugin

wrong

import htmlInjectionPlugin from 'vite-plugin-html-injection'

correct

import { htmlInjectionPlugin } from 'vite-plugin-html-injection'

Named export only; no default export.

IHtmlInjectionConfig

wrong

import { IHtmlInjectionConfig } from 'vite-plugin-html-injection'

correct

import type { IHtmlInjectionConfig } from 'vite-plugin-html-injection'

Use `import type` for TypeScript interfaces; they are not runtime values.

HtmlInjectionPlugin (CommonJS)

wrong

const htmlInjectionPlugin = require('vite-plugin-html-injection')

correct

const { htmlInjectionPlugin } = require('vite-plugin-html-injection')

CommonJS require must destructure; no default export.

Quickstart

Configures two injections: Open Graph meta tags always, Google Analytics only in production. Files are relative to project root.

// vite.config.js
import { defineConfig } from 'vite';
import { htmlInjectionPlugin } from 'vite-plugin-html-injection';

export default defineConfig({
  plugins: [
    htmlInjectionPlugin({
      order: 'pre',
      injections: [
        {
          name: 'Open Graph',
          path: './src/injections/og.html',
          type: 'raw',
          injectTo: 'head',
          buildModes: 'both',
        },
        {
          name: 'GA',
          path: './src/injections/ga.html',
          type: 'raw',
          injectTo: 'body',
          buildModes: 'prod',
        },
      ],
    }),
  ],
});

// src/injections/og.html:
<meta property="og:title" content="My Site" />

// src/injections/ga.html:
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'GA_MEASUREMENT_ID');</script>