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 >= 4.0.0
• mobx >= 3.1.0

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

Whenever your 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 as properties of the RouterStore class. You can then use the mobx API to observe and react to these observables:

@observable route // the current route
@observable previousRoute
@observable transitionRoute
@observable transitionError
@observable intersectionNode

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 router transition Start/Success/Cancel/Error the mobxPlugin invokes automatically these mobx actions exposed by the RouterStore:

• onTransitionStart(toState, fromState)
• onTransitionSuccess(toState, fromState, opts)
  • also calls the clearErrors() action
• onTransitionCancel(toState, fromState)
• onTransitionError(toState, fromState, err)

This ensures that these observables within the store are always up-to-date with the current state:

• @observable route
• @observable previousRoute
• @observable transitionRoute
• @observable transitionError
• @observable intersectionNode

Normally it's not necessary to manually call the store's actions, the plugin will do it for us. The only one probably worth calling manually (only when necessary) is clearErrors().

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.

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