Migrating from 3.x to 4.x
With version 4.0.0, router5 has been refactored. API for plugins, middleware functions,
canActivate and canDeactivate functions are now consistent.Router instanciation
router5 default export is now a
createRouter function as opposed to a Router5 class. The API is identical between createRouter(routes, options) and new Router5(routes, options).1
import createRouter from 'router5';
2
​
3
const router = createRouter(routes, options);
Copied!
Plugins moved
router5-history, router5-persistent-params and router5-listeners have been moved to router5 main repository. They are no longer individual modules but are distributed with router5 module.1
import browserPlugin from 'router5-plugin-browser';
2
import listenersPlugin from 'router5-plugin-listeners';
3
import persistentParamsPlugin from 'router5-plugin-persistent-params';
Copied!
The history plugin has been renamed 'browser plugin', to better describe its responsabilities. It deals with any URL related options and methods, to make router5 fully runtime environment agnostic:
useHash,hashPrefixandbaseoptions need to be passed tobrowserPlugin, not router5buildUrl,matchUrlandurlToPathmethods are no longer present by default and are added to your router instance bybrowserPlugin.
1
import browserPlugin from 'router5-plugin-browser';
2
​
3
router.usePlugin(browserPlugin({
4
useHash: true
5
}));
Copied!
Dependency injection reworked
Dependency injection has been reworked:
setAdditionalArgs has been renamed to setDependencies / setDependency and getAdditionalArgs has been renamed to getDependencies.1
router.setDependency('store', store);
2
// Or
3
router.setDependencies({ store });
4
​
5
router.getDependencies(); // => { store: store }
Copied!
Dependencies are no longer injected before
toState in middleware, canActivate and canDeactivate functions. Instead, they are injected alongside router, and are now available in plugins too. They are passed as an object of key / value pairs: it will now be easier to share code, plugins, middleware without sharing the exact same dependencies.Middleware and route lifecycle functions alignment
canActivate and canDeactivate functions have been reworked to be aligned with middleware functions.
1
function isAdmin(router, dependencies) {
2
return function (toState, fromState, done) {
3
/* boolean, promise or call done */
4
}
5
}
6
​
7
router.canActivate('admin', isAdmin);
Copied!
Boolean shortcuts are still supported (
canActivate('admin', isAdmin)).More importantly, they are now thunks: they are executed when added, and their returned functions will be executed when required by the router. It enables the use of closures.
Unknown routes (not found) supported
A new
allowNotFound option available, to give a new strategy to deal with unkown routes.If
defaultRoute option is not supplied and a path cannot be matched by the router, then the router will emit an ROUTE_NOT_FOUND error unless allowNotFound is set to true. In that case, the router will allow the transition to happen and will generate a state like the following one (given a User tried to navigate to an unknown URL /route-not-found):1
import { constants } from 'router5';
2
​
3
{
4
name: constants.UNKNOWN_ROUTE
5
params: { path: '/route-not-found' },
6
path: '/route-not-found'
7
}
Copied!
Other notable changes
- AMD and globals bundle are no longer distributed, use the UMD bundle instead
usePluginanduseMiddlewarebehave the same: you can supply one or more argument, and calling them thereafter will add more plugins / middleware functions (useMiddlewareused to overwrite middleware functions)errCodeshas been renamed toerrorCodes- Route parameters and transition options are now optional in
navigate, allowing users to only supply a route name and a done callback (router.navigate('home', () => { /* ... */ })) - A new
setRootNodePathfunction has been added to configure the path of the root node. It can be used for example to list a number of allowed query parameters for all routes ifstrictQueryParamsoption is set totrue.
Last modified 4yr ago