{"id":22911,"library":"vite-plugin-virtual-html","title":"vite-plugin-virtual-html","description":"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.","status":"active","version":"1.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/Windson1806/vite-plugin-virtual-html","tags":["javascript","vite-plugin","virtual-html","typescript"],"install":[{"cmd":"npm install vite-plugin-virtual-html","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-virtual-html","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-virtual-html","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only since v1.2.0; CJS require() will fail.","wrong":"const virtualHtml = require('vite-plugin-virtual-html')","symbol":"default (plugin function)","correct":"import virtualHtml from 'vite-plugin-virtual-html'"},{"note":"TypeScript type export; do not import at runtime.","wrong":"import { VirtualHtmlOptions } from 'vite-plugin-virtual-html'","symbol":"VirtualHtmlOptions (type)","correct":"import type { VirtualHtmlOptions } from 'vite-plugin-virtual-html'"},{"note":"Available only in TypeScript; used for custom page render functions.","wrong":"","symbol":"RenderFunction (type)","correct":"import type { RenderFunction } from 'vite-plugin-virtual-html'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport virtualHtml from 'vite-plugin-virtual-html';\n\nexport default defineConfig({\n  plugins: [\n    virtualHtml({\n      pages: {\n        index: '/src/pages/index/index.html',\n        about: '/src/pages/about/about.html',\n      },\n      indexPage: 'index',\n      data: { title: 'My App' },\n    }),\n  ],\n});\n\n// Create HTML files somewhere in project\n// /src/pages/index/index.html\n// /src/pages/about/about.html\n\n// Run `npm run dev` – plugin serves HTML from configured paths.\n// Run `npm run build` – plugin configures Rollup input and copies files.\n","lang":"typescript","description":"Basic setup for a multi-page app with virtual-html plugin, showing pages config, indexPage fallback, and global data."},"warnings":[{"fix":"Use ESM imports (import virtualHtml from 'vite-plugin-virtual-html') or downgrade to v1.1.x","message":"Dropped support for CJS in v1.2.0; require() will fail","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Ensure all configured HTML files exist or handle 404 gracefully","message":"html files must exist on disk in dev mode? No, but if missing, dev server returns 404 (since v1.1.20)","severity":"gotcha","affected_versions":">=1.1.20"},{"fix":"Remove manual input config; plugin auto-generates it from pages","message":"build.rollupOptions.input is overridden by plugin; manual input config may conflict","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Use 'template' key for HTML file path in page objects","message":"option 'page' was renamed to 'template' in v0.2.0","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Use '*' as key in injectCode to apply to all HTML files, or specify individual file paths","message":"injectCode only works when specifying html file pattern with '*' (globbing)","severity":"gotcha","affected_versions":">=1.1.16"},{"fix":"Set useCustom: false to revert to pre-1.2.4 behavior (appType auto-detected)","message":"viteConfig.appType is set to 'custom' by default since v1.2.4 (useCustom: true), which disables Vite's SPA fallback","severity":"breaking","affected_versions":">=1.2.4"},{"fix":"Clean up root HTML files manually if build is interrupted; known limitation","message":"Build copies HTML files to project root before building; if process crashes, root may get polluted","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Switch to ESM import or use dynamic import()","cause":"Using CJS require() with ESM-only version >=1.2.0","error":"TypeError: virtualHtml is not a function"},{"fix":"Verify all pages paths are correct and files exist; also ensure extraGlobPattern excludes dist","cause":"HTML file not found during build; often caused by missing file or incorrect paths in pages config","error":"[vite]: Rollup failed to resolve import \"...\" from \"...\""},{"fix":"Add the HTML file path to the pages config or ensure the requested URL matches a configured page","cause":"Dev mode: requested HTML file is not in pages config or path is wrong","error":"Error: ENOENT: no such file or directory, open '/path/to/project/root/index.html'"},{"fix":"Ensure each page value is either a string path or an object: { template: 'path', data: {...} }","cause":"pages entry must be a string (path) or an object with 'template' key; using other type","error":"Plugin page config: index is not a valid page config"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}