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
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mpa
✓ import mpa from 'vite-plugin-mpa'
✗ const mpa = require('vite-plugin-mpa')
ESM-only package; CommonJS require will fail.
mpa (with options)
✓ mpa({ scanDir: 'src/views', scanFile: 'index.{js,ts,jsx,tsx}', filename: 'template.html' })
✗ mpa({ pages: ['page1', 'page2'] })
Options are scanDir, scanFile, filename, open — not an explicit pages list.
MpaOptions
✓ import type { MpaOptions } from 'vite-plugin-mpa'
Available for TypeScript users; not required for JavaScript.
Basic setup with custom scan directory, entry file pattern, HTML filename, and URL to open on dev start.
// vite.config.ts
import { defineConfig } from 'vite'
import mpa from 'vite-plugin-mpa'
export default defineConfig({
plugins: [mpa({
scanDir: 'src/pages',
scanFile: 'main.{js,ts}',
filename: 'index.html',
open: '/page1/'
})]
})
Debug
Known issues
gotchaPlugin requires Vite >=2.0.0; older versions not supported.fixUpgrade Vite to 2.0.0 or later.
affects: <1.0.0 || Vite <2.0.0
gotchaThe plugin only rewrites the dev server URL; it does not generate HTML files. You must have an index.html in each page directory matching the 'filename' option.fixEnsure each page folder contains an HTML file (default: index.html).
affects: >=1.0.0
deprecatedThe 'open' option was added in v1.1.0; in v1.0.0 the first page was always opened automatically.fixUpgrade to v1.1.0+ to customize the open URL.
affects: 1.0.0
gotchaBuild output reorganization is experimental and may not work as expected; use shell scripts as a more reliable alternative.fixConsider using a postbuild script with shelljs or a build tool.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'vite-plugin-mpa'
Package not installed or ESM-only nature not handled.
fixInstall the package: yarn add vite-plugin-mpa -D / npm install vite-plugin-mpa --save-dev
TypeError: mpa is not a function
Using CommonJS require() which returns an object instead of the default export.
fixUse ES module import: import mpa from 'vite-plugin-mpa'
Error: No pages found. Check your scanDir, scanFile, and filename options.
Glob pattern does not match any page files.
fixVerify that pages exist at the configured scanDir with the correct entry file (e.g., main.js) and HTML (index.html).
Audit
Dependencies
fast-globrequiredUsed to scan for page entry files and HTML templates.