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

vite-plugin-virtual-html

library1.2.7jsnpmunverified

Vite plugin for flexible multi-page app (MPA) development, allowing HTML files to be placed anywhere in the project and configured via a pages map. Current stable version is 1.2.7, released periodically since 2020. Key differentiators: eliminates Vite's default HTML root restriction, provides dev-server interception for seamless MPA development, supports EJS templating with custom render functions, and includes automatic Rollup input configuration. Compared to vanilla Vite MPA, it offers a configurable pages structure similar to @vue/cli's pages option, with additional features like injectCode and urlTransformer.

web-framework devops

npm install vite-plugin-virtual-html

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-VIRTUA

vite-plugin-virtual-html

web-frameworkjavascriptv1.2.7

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.

default (plugin function)

✓ import virtualHtml from 'vite-plugin-virtual-html'

✗ const virtualHtml = require('vite-plugin-virtual-html')

ESM-only since v1.2.0; CJS require() will fail.

VirtualHtmlOptions (type)

✓ import type { VirtualHtmlOptions } from 'vite-plugin-virtual-html'

✗ import { VirtualHtmlOptions } from 'vite-plugin-virtual-html'

TypeScript type export; do not import at runtime.

RenderFunction (type)

✓ import type { RenderFunction } from 'vite-plugin-virtual-html'

Available only in TypeScript; used for custom page render functions.

Basic setup for a multi-page app with virtual-html plugin, showing pages config, indexPage fallback, and global data.

// vite.config.ts import { defineConfig } from 'vite'; import virtualHtml from 'vite-plugin-virtual-html'; export default defineConfig({ plugins: [ virtualHtml({ pages: { index: '/src/pages/index/index.html', about: '/src/pages/about/about.html', }, indexPage: 'index', data: { title: 'My App' }, }), ], }); // Create HTML files somewhere in project // /src/pages/index/index.html // /src/pages/about/about.html // Run `npm run dev` – plugin serves HTML from configured paths. // Run `npm run build` – plugin configures Rollup input and copies files.

Debug

Known issues

breakingDropped support for CJS in v1.2.0; require() will fail

fix

Use ESM imports (import virtualHtml from 'vite-plugin-virtual-html') or downgrade to v1.1.x

affects: >=1.2.0

gotchahtml files must exist on disk in dev mode? No, but if missing, dev server returns 404 (since v1.1.20)

fix

Ensure all configured HTML files exist or handle 404 gracefully

affects: >=1.1.20

gotchabuild.rollupOptions.input is overridden by plugin; manual input config may conflict

fix

Remove manual input config; plugin auto-generates it from pages

affects: >=0.2.0

deprecatedoption 'page' was renamed to 'template' in v0.2.0

fix

Use 'template' key for HTML file path in page objects

affects: >=0.2.0

gotchainjectCode only works when specifying html file pattern with '*' (globbing)

fix

Use '*' as key in injectCode to apply to all HTML files, or specify individual file paths

affects: >=1.1.16

breakingviteConfig.appType is set to 'custom' by default since v1.2.4 (useCustom: true), which disables Vite's SPA fallback

fix

Set useCustom: false to revert to pre-1.2.4 behavior (appType auto-detected)

affects: >=1.2.4

gotchaBuild copies HTML files to project root before building; if process crashes, root may get polluted

fix

Clean up root HTML files manually if build is interrupted; known limitation

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: virtualHtml is not a function

Using CJS require() with ESM-only version >=1.2.0

fix

Switch to ESM import or use dynamic import()

[vite]: Rollup failed to resolve import "..." from "..."

HTML file not found during build; often caused by missing file or incorrect paths in pages config

fix

Verify all pages paths are correct and files exist; also ensure extraGlobPattern excludes dist

Error: ENOENT: no such file or directory, open '/path/to/project/root/index.html'

Dev mode: requested HTML file is not in pages config or path is wrong

fix

Add the HTML file path to the pages config or ensure the requested URL matches a configured page

Plugin page config: index is not a valid page config

pages entry must be a string (path) or an object with 'template' key; using other type

fix

Ensure each page value is either a string path or an object: { template: 'path', data: {...} }

Upgrade

Version history

1.2.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Windson1806/vite-plugin-virtual-html ↗

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