Registry / web-framework / vite-plugin-history-api-fallback

vite-plugin-history-api-fallback

library0.0.1jsnpmunverified

A Vite plugin that serves as middleware for handling fallback to an index page when using HTML5 History API for multiple single-page applications. Version 0.0.1, early release with basic functionality. Differentiates from history-api-fallback by targeting Vite's dev server and supporting multiple SPA entries. Requires peer dependency vite ^2.6.4. Documentation is minimal; usage patterns may change in future versions.

web-framework devops

npm install vite-plugin-history-api-fallback

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-HISTOR

vite-plugin-history-api-fallback

web-frameworkjavascriptv0.0.1

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.

historyApiFallback

✓ import { historyApiFallback } from 'vite-plugin-history-api-fallback'

✗ const historyApiFallback = require('vite-plugin-history-api-fallback')

ESM-only package; CommonJS require will fail. Named export only.

default

✓ import historyApiFallback from 'vite-plugin-history-api-fallback'

✗ import { historyApiFallback } from 'vite-plugin-history-api-fallback'

Default import also works, but named export is explicitly documented.

VitePluginHistoryApiFallbackOptions

✓ import type { VitePluginHistoryApiFallbackOptions } from 'vite-plugin-history-api-fallback'

TypeScript users should import type for options interface.

Configures the plugin to rewrite requests for /app1 and /app2 to their respective index files, with a global fallback to /index.html.

import { defineConfig } from 'vite'; import { historyApiFallback } from 'vite-plugin-history-api-fallback'; export default defineConfig({ plugins: [ historyApiFallback({ rewrites: [ { from: /^\/app1/, to: '/app1/index.html' }, { from: /^\/app2/, to: '/app2/index.html' }, ], index: '/index.html', }), ], });

Debug

Known issues

gotchaPlugin only works in Vite's dev server, not during build. For production, you must configure a separate server (e.g., Express) with history-api-fallback middleware.

fix

Use a production-grade fallback middleware like connect-history-api-fallback for built output.

affects: >=0.0.1

breakingNamed export 'historyApiFallback' may be the default export in future versions. Documentation shows default import but named is also supported.

fix

Use import historyApiFallback from 'vite-plugin-history-api-fallback' to be safe across versions.

affects: 0.0.1

gotchaPlugin options 'rewrites' patterns are tested against the request URL, not the full path. Ensure patterns start with ^ to avoid unexpected matches.

fix

Use regex patterns anchored at start, e.g., /^\/app1/.

affects: >=0.0.1

deprecatedThe 'index' option defaults to '/index.html'. If you set it, ensure the path exists relative to the Vite root.

fix

Set 'index' to your actual fallback file, e.g., '/app/index.html'.

affects: >=0.0.1

Errors

Common errors & fixes

Cannot find module 'vite-plugin-history-api-fallback'

Package not installed or ESM require error

fix

Run npm install vite-plugin-history-api-fallback and use import instead of require.

TypeError: historyApiFallback is not a function

Wrong import style; package exports a function but used incorrect import

fix

Use import historyApiFallback from 'vite-plugin-history-api-fallback' or import { historyApiFallback } from 'vite-plugin-history-api-fallback'.

Error: The service should serve the fallback page, but the path /some/route is not found.

Rewrite pattern not matching or missing rewrites configuration

fix

Add a rewrite entry for the route, e.g., { from: /^\/some/, to: '/index.html' }.

Upgrade

Version history

0.0.1latest on npm

Audit

Dependencies

viterequiredPeer dependency required for plugin integration with Vite's dev server

Agent activity

16 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/Create-Peace/vite-plugin-history-api-fallback ↗

packagehttps://www.npmjs.com/package/vite-plugin-history-api-fallback ↗