{"id":22912,"library":"vite-plugin-virtual-mpa","title":"vite-plugin-virtual-mpa","description":"Vite plugin for building multi-page applications (MPA) with virtual file support and EJS templating. Current stable version 1.12.1, active development with regular minor/patch releases. Key differentiators: provides out-of-box MPA support without boilerplate, uses virtual HTML files (no physical templates needed), offers EJS template rendering, TypeScript types included, supports scan-based page auto-generation, and includes history fallback for dev/preview servers. Compatible with Vite >=2.0.0.","status":"active","version":"1.12.1","language":"javascript","source_language":"en","source_url":"https://github.com/emosheeep/vite-plugin-virtual-mpa","tags":["javascript","vite","vite-plugin","virtual","virtual-html","html","html-mpa","html-template","mpa","typescript"],"install":[{"cmd":"npm install vite-plugin-virtual-mpa","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-virtual-mpa","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-virtual-mpa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, core build tool","package":"vite","optional":false}],"imports":[{"note":"ESM-only; the plugin ships ESM and TypeScript definitions. CJS require will fail.","wrong":"const createMpaPlugin = require('vite-plugin-virtual-mpa')","symbol":"createMpaPlugin","correct":"import { createMpaPlugin } from 'vite-plugin-virtual-mpa'"},{"note":"Helper function for typed page creation; entirely optional.","wrong":"","symbol":"createPages","correct":"import { createPages } from 'vite-plugin-virtual-mpa'"},{"note":"Type-only import; can be used to type the options object externally.","wrong":"","symbol":"MpaOptions","correct":"import type { MpaOptions } from 'vite-plugin-virtual-mpa'"},{"note":"Default export is not exposed; use named import 'createMpaPlugin' instead.","wrong":"import { default } from 'vite-plugin-virtual-mpa'","symbol":"default","correct":"import vitePluginVirtualMpa from 'vite-plugin-virtual-mpa'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport { createMpaPlugin, createPages } from 'vite-plugin-virtual-mpa';\n\nconst pages = createPages([\n  {\n    name: 'index',\n    filename: 'index.html',\n    entry: 'src/pages/index/main.ts',\n  },\n  {\n    name: 'about',\n    filename: 'about.html',\n    entry: 'src/pages/about/main.ts',\n    template: 'src/pages/about/template.html', // custom EJS template\n  },\n]);\n\nexport default defineConfig({\n  plugins: [\n    createMpaPlugin({\n      pages,\n      verbose: true,\n      rewrites: [\n        { from: '/about', to: '/about.html' },\n      ],\n      transformHtml: (html, { page }) => {\n        // inject page-specific meta tags\n        return html.replace('</head>', `<meta name=\"page\" content=\"${page.name}\"></head>`);\n      },\n    }),\n  ],\n});","lang":"typescript","description":"Minimal MPA setup with two pages (index, about) using EJS template and custom rewrite rule."},"warnings":[{"fix":"Use import instead of require().","message":"v1.0.0 removed support for CommonJS require; ESM import is required.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use only alphanumeric characters, hyphens, or underscores for page names.","message":"page 'name' must not contain '/' characters; it is used for default redirect rules.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the modern API: createPages([]) or scanOptions.","message":"The 'pages' option was previously required to be passed directly; now can be built via createPages or scanOptions.","severity":"deprecated","affected_versions":"<0.9.0"},{"fix":"Ensure explicit page names are unique to avoid unexpected overrides.","message":"When using scanOptions, scanned pages with same name as explicit pages will be ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use Vite >=3 for full compatibility; the plugin is tested with Vite 4 and 5.","message":"Vite 2 used a different transformIndexHtml API; plugin is designed for Vite >=2, but behavior may differ.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Fix EJS syntax (e.g., close all <% %> tags). Check for missing closing '%>'. The plugin stops dev server on EJS error in recent versions.","cause":"EJS syntax error in a template file (e.g., unclosed tag).","error":"Error: [vite-plugin-virtual-mpa] Failed to compile EJS template: Could not find matching close tag for \"<% %>\""},{"fix":"Replace `const { createMpaPlugin } = require(...)` with `import { createMpaPlugin } from 'vite-plugin-virtual-mpa'`.","cause":"CommonJS require() used instead of ESM import.","error":"TypeError: createMpaPlugin is not a function"},{"fix":"Check the 'entry' path relative to project root. Ensure the file exists.","cause":"Entry file specified in page config does not exist at the given path.","error":"[plugin:vite-plugin-virtual-mpa] Cannot find module 'src/pages/.../main.ts'"},{"fix":"Remove slashes from page name; use only alphanumerics, hyphens, underscores.","cause":"Page 'name' contains a slash character.","error":"Error: Page name must not contain '/'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}