serve-fallback v1.2.0

serve-fallback

Node server middleware to serve a fallback page, relative to the url, instead of a 404 response

description

When a library/framework needs to handle url paths exclusively then the server should allow a reasonable fallback for any url path. When a typical hierarchy of folders contains index files then it's sometimes desirable to always fallback to them if a 404 error code would occur otherwise.

options

The value following each option is the default in case the relevant property is not specified on initialization.

{
  // the path to the served directory (default: .)
  root: '.',

  // the filename of the fallback file to serve in case of a non existent path (default: index.html)
  fallback: 'index.html',

  // whether or not to recurse backwards trying to find a valid fallback file to serve
  recurse: true,

  // whether or not to unconditionally fall back to serving the fallback file from root
  fallbackToRoot: false,

  // whether or not to use lodash's memoize function to check for path existence only once per path
  memoizePathChecks: true,

  // the cache constructor to use for the memoized paths (must use the )
  memoizeCacheConstructor: Map,

  // the maximum paths numbers to optimize before the cache is cleared to avoid excessive memory usage
  memoizedPathsMax: 1000,

  // optional function that accepts a message to log what serve-fallback will serve for each request
  log: null
}

usage

const serveFallback = require('serve-fallback');

// then, using the middleware configuration of browser-sync as an example:
{
  ...,
  middleware: [ ..., serveFallback({
    root: 'path/to/served/directory',
    fallback: 'default.html'
  }), ... ],
  ...
}

how it works

Given the following directory structure:

/

index.html

foo/

index.html

bar/

index.html

then the following table maps possibly requested paths to what is actually served (assuming the fallback filename is index.html):