{"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,"search_vec":"'1.2.7':36 '2020':40 'addit':90 'allow':16 'anywher':22 'app':13 'automat':68 'compar':72 'configur':27,71,80 'current':32 'custom':63 'default':46 'dev':52 'dev-serv':51 'develop':15,58 'differenti':42 'ej':60 'elimin':43 'featur':91 'file':18 'flexibl':9 'function':65 'html':5,17,47,102 'includ':67 'injectcod':93 'input':70 'intercept':54 'javascript':96 'key':41 'like':92 'map':31 'mpa':14,57,76 'multi':11 'multi-pag':10 'offer':78 'option':88 'page':12,30,81,87 'period':38 'place':21 'plugin':3,7,99 'project':25 'provid':50 'releas':37 'render':64 'restrict':49 'rollup':69 'root':48 'seamless':56 'server':53 'similar':83 'sinc':39 'stabl':33 'structur':82 'support':59 'templat':61 'typescript':103 'urltransform':95 'vanilla':74 'version':34 'via':28 'virtual':4,101 'virtual-html':100 'vite':2,6,44,75,98 'vite-plugin':97 'vite-plugin-virtual-html':1 'vue/cli':85","created_at":"2026-04-27T17:07:45.071085+00:00","updated_at":"2026-04-27T17:07:45.071085+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Windson1806/vite-plugin-virtual-html","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-plugin-virtual-html","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-18","next_check":"2026-07-26","install_tag":null}}