vite-plugin-htmlx

1.0.5 verified Mon Apr 27 auth: no javascript

A Vite plugin for HTML processing that provides EJS templating, HTML minification, and multi-page application support. Version 1.0.5, actively maintained with recent fixes. It is a fork and alternative to the stalled vite-plugin-html, aiming to address bugs and unmerged PRs. Key differentiators: EJS templates, flexible entry/template configuration, and inject tags with precise placement control.

Common errors

error Error: [plugin:vite-plugin-htmlx] The template file does not exist: ↓

cause Specified template path is incorrect or file missing.

fix

Ensure 'template' path in page config points to an existing HTML file, e.g., 'public/index.html'.

error Error: [vite] RollupError: ENOENT: no such file or directory, open '.../dist/index.html' ↓

cause Multi-page build missing 'filename' config causing output file overwrite or missing.

fix

Provide unique 'filename' for each MPA page entry, e.g., 'index.html', 'other.html'.

error TypeError: Cannot read properties of undefined (reading 'replace') ↓

cause Missing 'minify' option or invalid minify config.

fix

Set minify: true or provide valid MinifyOptions object.

Warnings

breaking Vite version requirement changed from >=3.0.0 to >=4.0.0 in v1.0.0 ↓

fix Upgrade Vite to 4.0.0 or later.

gotcha Default export is named 'html', not 'createHtmlPlugin'. Confusing when migrating from vite-plugin-html. ↓

fix Use 'import html from 'vite-plugin-htmlx'' or 'import { createHtmlPlugin } from 'vite-plugin-htmlx''.

gotcha Multi-page config requires 'page' to be an array of MpaPage objects; single page uses an object. ↓

fix For single page, use 'page: {...}'. For multi-page, use 'page: [{...}, ...]'.

deprecated The 'createHtmlPlugin' export is deprecated in favor of the default export 'html' since v1.0.0. ↓

fix Use default import 'import html from 'vite-plugin-htmlx'' instead.

gotcha Filename defaults to 'index.html'. If you forget to set 'filename' for MPA pages, the last page with no filename may conflict. ↓

fix Always set explicit 'filename' for each MPA page entry.

Install

npm install vite-plugin-htmlx

yarn add vite-plugin-htmlx

pnpm add vite-plugin-htmlx

Imports

default (html)

wrong

const html = require('vite-plugin-htmlx')

correct

import html from 'vite-plugin-htmlx'

ESM-only; CommonJS require will fail

createHtmlPlugin

wrong

import createHtmlPlugin from 'vite-plugin-htmlx'

correct

import { createHtmlPlugin } from 'vite-plugin-htmlx'

Named export; also available as default export 'html'

html (default)
wrong
```
import { html } from 'vite-plugin-htmlx'
```
correct
```
import html from 'vite-plugin-htmlx'
```
Default export is the function; named export is 'createHtmlPlugin'
UserOptions type
wrong
```
import { UserOptions } from 'vite-plugin-htmlx'
```
correct
```
import type { UserOptions } from 'vite-plugin-htmlx'
```
UserOptions is exported as a type, not a value; use type-only import in TypeScript

Quickstart

Sets up vite-plugin-htmlx with HTML minification and EJS template data injection for a single-page app.

import { defineConfig } from 'vite';
import html from 'vite-plugin-htmlx';

export default defineConfig({
  plugins: [
    html({
      minify: true,
      page: {
        entry: 'src/main.ts',
        inject: {
          data: {
            title: 'My App',
            injectScript: '<script src="./inject.js"></script>',
          },
        },
      },
    }),
  ],
});