/router5

Flexible and powerful universal routing solution

Primary LanguageJavaScriptMIT LicenseMIT

npm version Build Status Coverage Status Join the chat at https://gitter.im/router5/router5 styled with prettier

Official website: router5.github.io

router5

A simple, powerful, modular and extensible router, organising your named routes in a tree and handling route transitions. In its simplest form, router5 processes routing instructions and outputs state updates.

router5 is library and framework agnostic, works universally, and makes no asumption on your implementation. It favours convention over configuration, by giving you the means to observe route changes and to react to them. Afterall, why treat route changes any different than data changes?

To get started, look at Understanding router5, Get started, or watch my talk "Past and future of client-side routing" @ ReactiveConf 2016.

import createRouter from 'router5';
import browserPlugin from 'router5/plugins/browser';

const routes = [
    { name: 'home', path: '/home' },
    { name: 'profile', path: '/profile' }
];

const router = createRouter(routes)
    .usePlugin(browserPlugin());

"Past and future of client-side routing" @ ReactiveConf 2016

Flexible

router5 offers two essential tools: middlewares and plugins.

  • Middlewares allow you to decide the fate of a transition: you can delay it while performing asynchronous operations (data loading), fail it or simply hook some custom business logic.
  • Plugins are perfect for side-effects and 3rd party integration, by allowing you to react to router events: when it starts or stops, when a transition starts, is successful, has failed or has been cancelled. You can use them for updating the page title in the browser, sending page view analytic events, creating observables, sending your router state to a data store, etc...

Features

  • Default start route: a default route to navigate to on load if the current URL doesn't match any route. Similar to $routeProvider.otherwise() in Angular ngRoute module.
  • Unknown routes: if redirects to a default route is not how you want to handle unknown routes, router5 can generate state objects for them instead.
  • Start and stop
  • Nested named routes: routes are identified by names and path (containing parameters) so you don't have to manipulate URLs, even query parameters don't need to be specified on leaves only. directly. Routes can be nested, introducing the notion of route segments.
  • Segments activation: you can control whether or not a route can be accessed by specifying a canActivate function per node. Supports asynchronous results.
  • Segments deactivation: you can register segment components. On a route change, it will ask those components through their canDeactivate method if they allow navigation. Similar to Angular 2 and Aurelia routers. Supports asynchronous results.
  • Custom plugins: extend your router behaviour with custom plugins
  • Middleware functions: handle any data updates or other asynchronous actions with multiplebefore updating your view.
  • Universal applications: use on client and server side
  • Redirections: redirect to another route on error
  • You are in control! You decide what to do on a route change and how to do it.

Plugins

Several plugins are available in this repository:

  • Listeners plugin: allows you to add various types of route change listeners.
  • Browsers plugin: use of hash or not, URL building, HTML5 history integration.
  • Persistent parameters plugin: allows some query parameters to persist and survive navigation, without having to manually specify them for each transition.
import browserPlugin from 'router5/plugins/browser';
import listenersPlugin from 'router5/plugins/listeners';
import persistentParamsPlugin from 'router5/plugins/persistentParams';

Guides

API

Examples

Integration

Contributing

Please read contributing guidelines.

Related