Migrating from 7.x to 8.x

router5 is three and a half years old, and a few things have changed since the start! This year (2018), we went from 2,000 downloads a week to 10,000 downloads a week, so thank you! It gave me the motivation to perform a complete refactor with a necessary modernisation of all packages, something I had procrastinated over for a while. I'm always happy to know more about users of router5, so come and say I: who is using router5?.

With version 7, all packages have been rewritten in TypeScript, and tooling is now consistent across packages. A few breaking changes have been introduced.

No longer maintained packages

An unmaintained directory has been created to move packages which are no longer maintained. deku-router5 has been added to it: if you are interested in maintaining it, I'm happy to consider transferring ownership.

Changes per package



  • Plugins now accept a teardown method (alongside onStart, onStop, onTransitionSuccess, etc.): it will be called when a plugin is removed.


  • Plugins previously included with the router5 package (browser plugin, logger plugin, listeners plugin and persistent params plugin) have been moved to their own packages:

    • router5-plugin-browser

    • router5-plugin-logger

    • router5-plugin-listeners

    • router5-plugin-persistent-params

  • useMiddleware no longer returns your router instance, but a function to remove the added middleware. You can still pass multiple middleware, in which case calling the teardown function will remove all of them.

  • usePlugin no longer returns your router instance, but a function to remove the added plugin. You can still pass multiple plugins, in which case calling the teardown function will remove all of them.

  • hasPlugin method has been removed, and pluginName is no longer needed

  • Cloning is now done using a cloneRouter function, and it no longer re-uses existing dependencies

      import { cloneRouter } from 'router5'
      const clonedRouter = cloneRouter(router, dependencies)
  • When reload navigate option is set to true, fromState is no longer set to null: transitionPath has been updated to take into account this change, if you have middleware or plugins with custom logic, make sure you update them.



  • Hooks have been added: useRoute, useRouteNode and useRouter


  • Link has been renamed to ConnectedLink, and BaseLink has been renamed to Link

  • RouteProvider has been renamed to RouterProvider: there is now only one provider

  • react-router5 now requires React version 16.3.0 or above: it no longer uses the old context API. The migration path is quite easy:

    • If you are not using React 16.3.0 (or above), and cannot upgrade to it, a new package react-router5-hocs has been added: it is a drop-in replacement for react-router5 (Link component names stil need changed, see point above)

    • If you are using React 16.3.0 and above, you are good to continue using react-router5 (see breaking changes above)



  • For use with immutable.js, import router5Reducer from redux-router5-immutable



  • Undocumented redirect helper has been removed: it's no longer needed with forwardTo.

Last updated