Simple fallback for Express-served single page apps that use the HTML5 History API for client side routing.
Last updated 2 years ago by seb .
ISC · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install express-history-api-fallback 
SYNC missed versions from official npm registry.


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.

Current Tags

  • 2.2.1                                ...           latest (2 years ago)

5 Versions

  • 2.2.1                                ...           2 years ago
  • 2.2.0                                ...           2 years ago
  • 2.1.0                                ...           3 years ago
  • 2.0.0                                ...           4 years ago
  • 1.0.0                                ...           4 years ago
Maintainers (1)
Today 61
This Week 3,137
This Month 23,776
Last Day 1,422
Last Week 8,796
Last Month 38,045
Dependencies (0)
Dev Dependencies (13)

Copyright 2014 - 2016 © |