mobx-router5

Router5 integration with mobx. If you develop with React, use this package with react-mobx-router5. This plugin represents the source of truth for the @observer components exposed by react-mobx-router5.
This plugin can also be used standalone together with mobx.

Requirements

• router5 >= 6.1.2
• mobx >= 5.0.0 If you use Mobx < 5 install "^4.0.0" version

Notice Mobx@5 introduced breaking changes, please follow the migration guide

These are considered peerDependencies that means they should exist in your installation, you should install them yourself to make this plugin work. The package won't install them as dependencies.

Install

npm install mobx-router5

How it works

Before using this plugin it is necessary that you understand how router5 works.

Whenever you performs a router5's transition from one state to another and that transition is started, canceled, it's successful or it has a transition error this plugin exposes all this info as mobx observables references properties of the RouterStore class.
You can then use the mobx API to observe and react to these observables:

@observable.ref route; // Current Route - Object  
@observable.ref previousRoute; // Object
@observable.ref transitionRoute; // Object
@observable.ref transitionError; // Object
@observable.ref intersectionNode; // String
@observable.ref canActivate; // Array
@observable.ref canDeactivate; // Array

How to use

• Create a router store instance from the RouterStore class
• Create and configure a router instance
• Add the plugin to the router instance, passing the store to the plugin
• Use the store methods to perform routing or use your router instance directly
  • The only (non-action) method provided is navigate that is just an alias for router5 navigate
• Observe the observable properties exposed by the store

import {createRouter} from 'router5';
import loggerPlugin from 'router5/plugins/logger'; 
import browserPlugin from 'router5/plugins/browser';
import routes from './routes';
import {mobxPlugin, RouterStore} from 'mobx-router5';

// Instantiate it directly or extend the class as you wish before invoking new
const routerStore = new RouterStore();
  
export default function configureRouter(useLoggerPlugin = false) {
  const router = createRouter(routes, {defaultRoute: 'home'})
    .usePlugin(mobxPlugin(routerStore)) // Important: pass the store to the plugin!
    .usePlugin(browserPlugin({useHash: true}));
  
  if (useLoggerPlugin) {
    router.usePlugin(loggerPlugin) ;
  }
  
  return router;
}

RouterStore

The core idea of this little plugin is the router store.
The plugin will automatically call the actions (in fact mobx @actions) exposed by the store.
By default you can just import the class RouterStore, create a new instance, pass it to the plugin and just use it.

Actions

On route transition Start/Success/Cancel/Error the mobxPlugin invokes automatically these mobx actions exposed by the RouterStore:

• onTransitionStart(toState, fromState)
  • set the transitionRoute
  • clear the transitionError
• onTransitionSuccess(toState, fromState, opts)
  • set the route, previousRoute, canActivate, canDeactivate and interserctionNode
  • also calls the clearErrors() action
• onTransitionCancel(toState, fromState)
  • reset the transitionRoute
• onTransitionError(toState, fromState, err)
  • set the transitionRoute, previousRoute and transitionError

Normally it's not necessary to manually call these actions, the plugin will do it for us.

The only one probably worth calling manually (only when necessary) is clearErrors(): it resets the transitionRoute and transitionError.

Router instance reference inside the store

When you add the plugin to the router with

router.usePlugin(mobxPlugin(routerStore))

the router reference is added to the store, so that you can call all the router's methods from the store itself, for example:

routerStore.router.navigate('home', {}, {})

and all other router5's API listed here.

Store reference inside the router's dependencies

The plugin also adds the routerStore (the instance) to the router dependencies with

router.setDependency('routerStore', routerStore);

That means that you can access your store from router5's lifecycle methods (canActivate, canDeactivate), middleware or plugins, see router5 docs on this topic.

This creates indeed a cross referece, that is, the store has a reference of the router and the router has a reference of the store. In most cases this should not create any trouble but be aware of this for cases I haven't foreseen.

Your own store

If you know what you are doing you can subclass or create yor own store, making sure you implement at least the actions listed above and a setRouter(router) method.

Contributing

Please refer to the CONTRIBUTING.md file.
Please notice that this would require node >=8 as some dev packages require it (for example semantic-release)

Acknowledgments

• The structure and build process of this repo are based on babel-starter-kit
• I've taken the redux-router5 plugin as example for developing this one
• Thanks to egghead.io for the nice tips about open source development on their free course
• Special thanks to Thomas Roch for the awesome router5 ecosystem