Routerjs - React

React bindings for RouterJS. These bindings simplify the usage of RouterJS in a react project

• 1. Installation
• 2. Usage
• 3. Link
• 4. View
• 5. RouterContext and useRouter hook
• 6. Advanced

1. Installation

You need to install both RouterJS and react-routerjs.

with yarn

yarn add routerjs react-routerjs

or with npm

npm install --save routerjs react-routerjs

2. Usage

The main component provided by this library is a RouterProvider to which you need to pass your configured router. You should put this provider on a top position in your react project. To know how to define routes refer to RouterJS documentation

import { createRouter } from 'routerjs';
import { RouterProvider } from 'react-routerjs';
import App from './App'; // you react app code

const router = createRouter()
  .get('/', () => {
    // route handler
  });


ReactDOM.render(
  <RouterProvider router={router}>
    <App />
  </RouterProvider>
, document.getElementById('app'));

// Run the router after the render method 
// if you want to parse also the entrance url
router.run();

Any other component provided by this library must be a descendant of the RouterProvider.

3. Link

A Link component is provided to easily create anchors. Always remember that also normal anchors will fire router events (see documentation for this) but the advantage of using the Link component is that you can omit the basePath, if any, since it will automatically prepend it to any href. Link takes the same attributes as an anchor

<Link href="/post/14">Article on cats</Link>

If basePath is /blog

<Link href="/posts">Post list</Link>
// is equivalent to
<a href="/blog/posts">Post list</a>

NOTE: Link will always run your handlers even if bindClick is set ot false in your router engine, as explained here.

4. View

react-routerjs applies an opinionated way of showing a view depending on the route. This is done through two components:

• a withView middleware
• a RouteView component

Use withView to declare which View to show on a route. It accepts a function that gets the current req and context. You may use it to pass parameters to your components.

import { createRouter } from 'routerjs';
import { withView } from 'react-routerjs';
import UserList from './UserList';
import Post from './Post';

const router = createRouter()
  .get('/users', withView((req, ctx) => <UserList />)(
    async (req, context) => {
      context.users = await loadUsers();
    }
  ))
  .get('/post/:id', withView((req, ctx) => <Post id={req.params.id} />)(
    (req, context) => {
      await setPostAsVisited(req.params.id);
    }
  ))
  .run();

you can also use react.lazy and return a promise instead. This way your component will be lazy loaded only when the route is visited!

// ... as before
const Post = React.lazy(() => import('./Post'));

router
  .get('/post/:id', withView((req, ctx) => <Post id={req.params.id} />)(
    (req, context) => {
      await setPostAsVisited(req.params.id);
    }
  ))

Now the view will be shown in your application where the RouteView placeholder is placed

import { RouteView } from 'react-routerjs';

<div className="content">
  <RouteView />
</div>

RouteView component accepts a fallback props since it internally uses React Suspense.

The couple withView and RouteView takes another parameter, called target. The default target is called main but you can specify a different one. This let you build more complex applications. In this example we define another target called sidebar to choose which view to show in a sidebar

import { createRouter, compose } from 'routerjs';
import { withView } from 'react-routerjs';

import UserList from './UserList';
import UserSidebar from './UserSidebar';

const router = createRouter()
  .get('/users', compose(
    withView(<UserList />),  // this is in target "main" which is the default
    withView(<UserSidebar />, 'sidebar'), // this is in target "sidebar"
  )(
    async (req, context) => {
      context.users = await loadUsers();
    }
  ));

Later, in your application

<div className="main">
  <div className="content">
    /* This will show the UserList component */
    <RouteView target="main" /> 
  </div>
  <div className="sidebar">
    /* This will show the UserSidebar component */
    <RouteView target="sidebar" />
  </div>
</div>

You can do the same in case of error just using withErrorView

import { createRouter, compose } from 'routerjs';
import { withErrorView } from 'react-routerjs';

import View404 from './View404';

const on404 = () => {
  // ...
}

const router = createRouter()
  // ....
  .error(
    404, 
    withErrorView((error, ctx) => <View404 path={ctx.path} />)(on404)
  )

The only difference is that you have access to the error, not the request.

RouteView internally uses Suspense, if you want to remove it pass the props disableSuspense.

5. RouterContext and useRouter hook

To access current router context and router methods in your components, you can use the useRouter hook

import { useRouter } from 'react-routerjs';

const MyComponent = () => {
  const routerContext = useRouter();

  if(routerContext) {
    routerContext.router.navigate('/somewhere'); // method to navigate
    routerContext.context.path(); // access current path
    routerContext.context.currentUser; // For example, if your route populate the context with the user
  }
}

The routerContext contains the following properties:

The router instance with all the router methods.
The most useful will probably be:

• router.navigate: a method to navigate to a desired url
• router.buildUrl: a method to build an url considering the basePath

and the route context

• context: the router context which contains

Refer to its documentation to know how the context works.

NOTE remember that routerContext can be null, so check it before usage

If you cannot use hooks, you can use the regular react context to access the same values.

6. Advanced

This is pretty much all you need to know to use RouterJS with React. Consider that RouterJS is thought to be framework agnostic and this is just one of the possible way to use it with React. If you find that this way is not the best for your project, or you want to implement a different coupling between React and RouterJS, you should create your own implementation: it's very fun!

To do it, study carefully how RouterJS works and remember that the router has an handy method, router.always((context) => {}), that let you attach some code and execute it for any route! Also, look at the implementation of this project to get some idea.