vite-plugin-html-template-mpa

1.0.33 verified Mon Apr 27 auth: no javascript

Vite plugin for HTML template injection and multi-page application (MPA) support. Current stable version 1.0.33, with ongoing active development. Provides HTML minification, EJS template data injection, custom entry/template, and build output configuration including HTML hash, directory restructuring, and prefix replacement. Differentiates from alternatives like vite-plugin-html by actively supporting Vite 5 and offering built-in MPA features with a pages configuration system, while the older plugin is unmaintained. Ships TypeScript types.

Common errors

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

cause Plugin not installed or wrong import path.

fix

Run pnpm add vite-plugin-html-template-mpa and use default import as shown in quickstart.

error TypeError: htmlTemplate is not a function ↓

cause Using named import instead of default import.

fix

Use import htmlTemplate from 'vite-plugin-html-template-mpa'.

error Vite build error: The 'pagesDir' option is required for multi-page mode. ↓

cause Missing `pagesDir` configuration for MPA.

fix

Add pagesDir to the plugin options, e.g., pagesDir: 'src/views'.

Warnings

breaking API changes in version > 1.0.0: options and behavior differ from earlier versions. ↓

fix Refer to the updated documentation; the default `pagesDir` changed to `src/views`.

gotcha Multi-page app directory default changed to `src/views`; if your pages are elsewhere, set `pagesDir` explicitly. ↓

fix Set `pagesDir` to your actual pages directory, e.g., `pagesDir: 'src/pages'`.

gotcha Page configuration `urlParams` adds query parameters to the root navigation page only. ↓

fix Use `urlParams` for adding parameters to the generated index page links, not individual page templates.

deprecated Previous plugin `vite-plugin-html` is unmaintained; this plugin intends to replace its functionality for SPA. ↓

fix Migrate from `vite-plugin-html` to this plugin for Vite 5 compatibility.

Install

npm install vite-plugin-html-template-mpa

yarn add vite-plugin-html-template-mpa

pnpm add vite-plugin-html-template-mpa

Imports

htmlTemplate

wrong

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

correct

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

ESM-only; plugin provides a default export.

Options

wrong

import { Options } from 'vite-plugin-html-template-mpa'

correct

import type { Options } from 'vite-plugin-html-template-mpa'

Type-only import; Options is a TypeScript interface, not a runtime value.

PageOptions

import type { PageOptions } from 'vite-plugin-html-template-mpa'

Type-only import for the page configuration interface.

Quickstart

Configures Vite for MPA with custom pages, HTML minification, and build output restructuring.

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

// Multi-page application configuration
export default defineConfig({
  plugins: [
    htmlTemplate({
      pagesDir: 'src/views',
      pages: {
        'index': {
          title: 'Home',
          entry: 'src/views/index/main.ts',
          template: 'public/index.html',
        },
        'about': {
          title: 'About Us',
          entry: 'src/views/about/main.ts',
          inject: {
            data: {
              title: 'About',
            },
            tags: [
              { injectTo: 'head', tag: 'meta', attrs: { name: 'description', content: 'About page' } }
            ],
          },
        },
      },
      minify: true,
      buildCfg: {
        moveHtmlTop: true,
        htmlHash: true,
      },
    }),
  ],
});