Simple fallback for Express-served single page apps that use the HTML5 History API for client side routing.

Downloads in past


2.2.17 years ago8 years agoMinified + gzip package size for express-history-api-fallback in KB


A tiny, accurate, fast Express middleware for single page apps with client side routing.
Build Status
Works as a middleware for Express. Can be used as either an application middleware or a router middleware.
import fallback from 'express-history-api-fallback'
import express from 'express'
const app = express()
const root = `${__dirname}/public`
app.use(fallback('index.html', { root }))
Or in ECMAScript 5:
var fallback = require('express-history-api-fallback')
var express = require('express')
var app = express()
var root = __dirname + '/public'
app.use(fallback('index.html', { root: root }))

fallback(path, options)

Returns a middleware for use by Express applications and routers.
Arguments are passed to res.sendFile() in express@>=v4.8.0, or res.sendfile() otherwise.
Absolute path:
app.use(fallback(__dirname + '/dist/app.html'))
Relative path:
app.use(fallback('dist/app.html', { root: __dirname }))


Location of the HTML file containing single page app entry point.
Unless the root option is set in the options object, path must be an absolute path of the file.


Valid options are maxAge, root, lastModified, headers, and dotfiles. See Response.sendFile() for details. Note that only maxAge and root are supported with express@<4.8.

But doesn't this already exist?

Yes, but this implementation is much better.
  • Only for GET (and HEAD) requests: The fallback should not serve your index.html for POST or other requests.
  • Only for HTML requests: Never serve mistakenly for JS or CSS or image or other static file requests. Less debugging headaches.
  • Only when needed: Serve the fallback only when the file is missing.
  • High performance: Let res.sendFile() in Express >=4.8.0 do the heavy lifting of serving the file.
  • Minimal code: Just a few lines. No magic. No complexity.

See the blog post "Single Page App Routing with Express & Node.js" for an overview of the problems with alternative middlewares.