vite-plugin-html-template

1.2.2 verified Mon Apr 27 auth: no javascript

Vite plugin for generating HTML entry files from templates, similar to html-webpack-plugin for webpack. Version 1.2.2 provides EJS/lodash.template syntax support, multi-page application (MPA) configuration via pagesDir and pages options, and works seamlessly with vite-plugin-mpa. It eliminates the need for manual index.html files per entry by virtualizing HTML. Ideal for migrating from webpack or using Vue CLI-like pages configuration in Vite projects. Ships TypeScript types and is actively maintained.

Common errors

error Error: ENOENT: no such file or directory, open 'public/index.html' ↓

cause Default template path './public/index.html' not found.

fix

Ensure public/index.html exists or provide custom template path in options.

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

cause Missing or malformed 'pages' definition in configuration.

fix

Define at least one page with 'template' and 'title' keys. Example: pages: { main: { template: './index.html', title: 'App' } }

error ReferenceError: title is not defined (in template) ↓

cause Template uses EJS variable but 'data' does not include it.

fix

Pass missing variables via 'data' option: data: { title: 'My Page' }

Warnings

breaking Version 1.x has different options structure compared to earlier 0.x. 'pagesDir' default was removed; 'pages' must be defined explicitly. ↓

fix Update vite.config.ts to provide a 'pages' object; see README options.

deprecated Support for lodash template syntax is deprecated in favor of EJS; will be removed in 2.0. ↓

fix Switch to EJS syntax in HTML templates: use <%= title %> instead of {{ title }}.

gotcha The plugin requires a valid HTML template file; missing or misconfigured template paths will result in build failure without clear error messages. ↓

fix Verify template paths are correct relative to project root, and that files exist.

gotcha Plugin may conflict with other Vite plugins that modify HTML (e.g., vite-plugin-html) - order matters. ↓

fix Place htmlTemplate after other HTML-modifying plugins in the plugins array.

Install

npm install vite-plugin-html-template

yarn add vite-plugin-html-template

pnpm add vite-plugin-html-template

Imports

default (htmlTemplate)

wrong

const htmlTemplate = require('vite-plugin-html-template')

correct

import htmlTemplate from 'vite-plugin-html-template'

ESM-only; CommonJS require will throw. Use default import.

htmlTemplate (named)

wrong

import { default as htmlTemplate } from 'vite-plugin-html-template'

correct

import { htmlTemplate } from 'vite-plugin-html-template'

The package also exports a named export 'htmlTemplate' identical to default. Both work.

defineConfig (Vite)
wrong
```
import { defineConfig } from 'vite-plugin-html-template'
```
correct
```
import { defineConfig } from 'vite'
```
Common mistake: confusing Vite's defineConfig with the plugin's exports.

Quickstart

Shows MPA configuration with two pages and custom template data, using TypeScript in vite.config.ts.

import { defineConfig } from 'vite';
import htmlTemplate from 'vite-plugin-html-template';

export default defineConfig({
  plugins: [
    htmlTemplate({
      pages: {
        index: {
          template: './public/index.html',
          title: 'Homepage'
        },
        about: {
          template: './src/about/index.html',
          title: 'About Us'
        }
      },
      data: {
        appName: 'My App'
      }
    })
  ]
});