{"id":22686,"library":"vite-plugin-history-api-fallback","title":"Vite Plugin History API Fallback","description":"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.","status":"active","version":"0.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/Create-Peace/vite-plugin-history-api-fallback","tags":["javascript","vite-plugin","vite-history","history-api-fallback"],"install":[{"cmd":"npm install vite-plugin-history-api-fallback","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-history-api-fallback","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-history-api-fallback","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for plugin integration with Vite's dev server","package":"vite","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require will fail. Named export only.","wrong":"const historyApiFallback = require('vite-plugin-history-api-fallback')","symbol":"historyApiFallback","correct":"import { historyApiFallback } from 'vite-plugin-history-api-fallback'"},{"note":"Default import also works, but named export is explicitly documented.","wrong":"import { historyApiFallback } from 'vite-plugin-history-api-fallback'","symbol":"default","correct":"import historyApiFallback from 'vite-plugin-history-api-fallback'"},{"note":"TypeScript users should import type for options interface.","symbol":"VitePluginHistoryApiFallbackOptions","correct":"import type { VitePluginHistoryApiFallbackOptions } from 'vite-plugin-history-api-fallback'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport { historyApiFallback } from 'vite-plugin-history-api-fallback';\n\nexport default defineConfig({\n  plugins: [\n    historyApiFallback({\n      rewrites: [\n        { from: /^\\/app1/, to: '/app1/index.html' },\n        { from: /^\\/app2/, to: '/app2/index.html' },\n      ],\n      index: '/index.html',\n    }),\n  ],\n});","lang":"typescript","description":"Configures the plugin to rewrite requests for /app1 and /app2 to their respective index files, with a global fallback to /index.html."},"warnings":[{"fix":"Use a production-grade fallback middleware like connect-history-api-fallback for built output.","message":"Plugin 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.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Use import historyApiFallback from 'vite-plugin-history-api-fallback' to be safe across versions.","message":"Named export 'historyApiFallback' may be the default export in future versions. Documentation shows default import but named is also supported.","severity":"breaking","affected_versions":"0.0.1"},{"fix":"Use regex patterns anchored at start, e.g., /^\\/app1/.","message":"Plugin options 'rewrites' patterns are tested against the request URL, not the full path. Ensure patterns start with ^ to avoid unexpected matches.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Set 'index' to your actual fallback file, e.g., '/app/index.html'.","message":"The 'index' option defaults to '/index.html'. If you set it, ensure the path exists relative to the Vite root.","severity":"deprecated","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run npm install vite-plugin-history-api-fallback and use import instead of require.","cause":"Package not installed or ESM require error","error":"Cannot find module 'vite-plugin-history-api-fallback'"},{"fix":"Use import historyApiFallback from 'vite-plugin-history-api-fallback' or import { historyApiFallback } from 'vite-plugin-history-api-fallback'.","cause":"Wrong import style; package exports a function but used incorrect import","error":"TypeError: historyApiFallback is not a function"},{"fix":"Add a rewrite entry for the route, e.g., { from: /^\\/some/, to: '/index.html' }.","cause":"Rewrite pattern not matching or missing rewrites configuration","error":"Error: The service should serve the fallback page, but the path /some/route is not found."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}