mobx-state-router

MobX powered router for React apps

Usage no npm install needed!

<script type="module">
  import mobxStateRouter from 'https://cdn.skypack.dev/mobx-state-router';
</script>

README

MobX State Router

npm styled with prettier Travis Coverage Status Commitizen friendly

MobX-powered router for React apps.

Features

  • State is decoupled from the UI. UI is simply a function of the state.
  • UI is no longer responsible for fetching data. Data is now fetched during state transitions using router hooks.
  • The router can override routing requests based on the application state. For example, it can redirect to the Sign In page if the user is not logged in.
  • Supports
    • 404 (Not Found) errors
    • Server-Side Rendering

Learn how to use mobx-state-router in your own project.

Contributors

Make sure all your commit messages conform to the Angular Commit Message Conventions.

To simplify this process, we have included Commitizen as a dependency of this project. Always execute the following command sequence to commit your changes. It will prompt you to fill out any required commit fields interactively.

git add --all
yarn cz-commit # interactive conventional commit
git push

Testing local builds

To test local builds with examples in the examples folder, follow the steps listed below:

  • Build the package
yarn build:local  # creates a dist folder
  • Create a tarball from the package
npm pack  # packages src and dist into a tarball with name [package-name]-[version].tgz
  • Go to an example in the examples directory and add the tarball as a dependency
cd examples/mobx-shop
yarn add ../../[package-name]-[version].tgz
  • Run the example
yarn start

Release to NPM

  • Change the version number in package.json. Use semver. For pre-release versions add a suffix & build number, e.g 5.0.0-beta.1.

  • Commit and push (see above)

  • Build the package

yarn build:local
  • Release to npm
npm publish             # for normal release (adds `latest` tag)
npm publish --tag next  # for pre-release (adds `next` tag)
  • Tag the release and push the tag to remote

Publishing docs to GitHub Pages

Make sure you are connected to GitHub using your SSH key.

cd website
yarn
GIT_USER=nareshbhatia CURRENT_BRANCH=master USE_SSH=true yarn publish-gh-pages

Credits

mobx-state-router is based on ideas from several Open Source projects. I am grateful to the developers of these projects for their contributions. Special thanks go to the following contributions:

How to decouple state and UI (a.k.a. you don’t need componentWillMount)
This article by Michel Weststrate provided the initial inspiration for writing mobx-state-router. It explains the downsides of mixing State and UI and how to untangle the mess!

mobx-router
This library by Kitze is a good implementation of Michel Weststrate's ideas. I have borrowed some concepts from this implementation and then added my own. Thanks Kitze!

router5
This is a more extensive library for routing. It's unique feature is that routes are organized as a tree, made of segments and nodes. It aims to be framework agnostic and uses middleware and plugins to adapt to different frameworks. Of course, with flexibility comes complexity. mobx-state-router makes some choices for you to keep the overall learning curve simple.