@overra/koa-history-api-fallback
v2.0.1
Published
Provides a fallback for non-existing directories so that the HTML 5 history API can be used for Koa.
Downloads
4
Readme
@overra/koa-history-api-fallback
Koa v2 implementation of connect-history-api-fallback
Introduction
This is a fork of koa-history-api-fallback which is a simple rewrite of connect-history-api-fallback
Usage
The middleware is available through NPM and can easily be added.
npm install --save @overra/koa-history-api-fallback
Import the library
const historyApiFallback = require('koa-history-api-fallback');
const app = new Koa();
app.use(historyApiFallback());
To use this with koa-webpack-middleware you'll need to do the following.
const {devMiddleware, hotMiddleware} = require('koa-webpack-middleware')
const historyApiFallback = require('@overra/koa-history-api-fallback')
// ...
const app = new Koa()
const webpackMiddleware = devMiddleware(compiler, options)
app.use(webpackMiddleware) // serve up webpack content
app.use(historyApiFallback()) // catch any other requests and redirect to /index.html
app.use(webpackMiddleware) // serve up webpack content
Options
You can optionally pass options to the library when obtaining the middleware
const middleware = historyApiFallback({});
index
Override the index (default /index.html
)
historyApiFallback({
index: '/default.html'
});
rewrites
Override the index when the request url matches a regex pattern. You can either rewrite to a static string or use a function to transform the incoming request.
The following will rewrite a request that matches the /\/soccer/
pattern to /soccer.html
.
historyApiFallback({
rewrites: [
{ from: /\/soccer/, to: '/soccer.html'}
]
});
Alternatively functions can be used to have more control over the rewrite process. For instance, the following listing shows how requests to /libs/jquery/jquery.1.12.0.min.js
and the like can be routed to ./bower_components/libs/jquery/jquery.1.12.0.min.js
. You can also make use of this if you have an API version in the URL path.
historyApiFallback({
rewrites: [
{
from: /^\/libs\/.*$/,
to: function(context) {
return '/bower_components' + context.parsedUrl.pathname;
}
}
]
});
The function will always be called with a context object that has the following properties:
- parsedUrl: Information about the URL as provided by the URL module's
url.parse
. - match: An Array of matched results as provided by
String.match(...)
.
verbose
This middleware does not log any information by default. If you wish to activate logging, then you can do so via the verbose
option or by specifying a logger function.
historyApiFallback({
verbose: true
});
Alternatively use your own logger
historyApiFallback({
logger: console.log.bind(console)
});