connect-history-api-fallback is a robust middleware designed for Single Page Applications (SPAs) leveraging the HTML5 History API. It addresses the common challenge where direct access to client-side routes (e.g., `/about` or `/users/123`) or page refreshes result in a 404 "Not Found" error from the web server, as these paths do not correspond to physical files. The middleware intercepts such requests, identifies those that accept `text/html` and are not direct file requests (by default, paths containing a dot), and then rewrites the request URL to a specified index file, typically `/index.html`. This allows the SPA's client-side router to take over and render the correct view. The current stable version is 2.0.0. While there isn't a strict release cadence, updates generally address compatibility, performance, or new configuration options. Key differentiators include its configurable `index` path, powerful `rewrites` option supporting both static strings and dynamic functions based on request context, and fine-grained control over accepted HTML headers and dot-file handling. It seamlessly integrates with Connect and Express-based Node.js servers.
npm install connect-history-api-fallbackVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to integrate `connect-history-api-fallback` with an Express server to handle client-side routing for a Single Page Application (SPA). It correctly places the middleware to serve static assets while ensuring that direct URL access or page refreshes on SPA routes gracefully fall back to `index.html`.
Remove the `logger` option from your configuration. If you need logging, set `verbose: true`.
Review your `disableDotRule` configuration. If you previously relied on the `true` default, you might need to explicitly set `disableDotRule: true` to revert to rewriting paths with dots, though this is rarely recommended for static assets.
No direct fix is usually required as the new default is more comprehensive. If you had a custom `htmlAcceptHeaders` array, ensure it still meets your application's needs.
Ensure all objects within your `rewrites` array specify both a `from` (RegExp) and `to` (string or function) property.
Ensure `app.use(express.static('public'));` runs before `app.use(history());`, and consider running `app.use(express.static('public'));` again *after* `app.use(history());` to serve the rewritten `index.html`.Always provide the `index` option as an absolute HTTP path (e.g., `/default.html`). Do not use relative paths or file system paths here.
Ensure your API routes are defined *before* the `connect-history-api-fallback` middleware, or use the `rewrites` option to explicitly exclude API paths (e.g., `rewrites: [{ from: /\/api\/.*$/, to: (context) => context.parsedUrl.pathname }]`) to prevent them from being rewritten.Ensure `connect-history-api-fallback` middleware is installed and correctly configured in your server.js, placed before any generic 404 handlers, and after the first static file serving middleware.
For CommonJS, use `const history = require('connect-history-api-fallback');`. For ESM, use `import history from 'connect-history-api-fallback';`.In v2.0.0+, `disableDotRule` defaults to `false`, which should prevent this. For earlier versions or if you've overridden it, ensure `disableDotRule` is explicitly `false` (or unset for v2+ default behavior). Also, ensure `express.static` (or equivalent) for your static assets is called *before* `app.use(history())` in your middleware chain.
Place your API router middleware *before* `app.use(history())`. Alternatively, use the `rewrites` option to create a rule that explicitly allows API paths to pass through (e.g., `rewrites: [{ from: /\/api\/.*$/, to: (context) => context.parsedUrl.pathname }]`).No dependency data recorded yet.