React Router Mapping

This library has as auxiliary tools the developers to have a better way to map, group and manage the routes of their applications.

Before starting

This library works in conjunction with React Router, using certain features that would not need to be rewritten. Therefore, carefully read each section of this document.

Installation

npm install react-router-mapping

How to use

import React from 'react';
import { BrowserRouter, Routes } from 'react-router-dom';
import { MappingProvider, useMap } from 'react-router-mapping';

export default () => {

  const [ MainRoutes, mapRoutes ] = useMap([
    {
      name : 'home',
      label : 'Home',
      path : '/',
      element : <Home />,
    },
    {
      path : '/route-one',
      element : <Template />,
      routes : [
        {
          name : 'route-one',
          label : 'Route One',
          element : <RouteOne />,
          index : true,
        },
        {
          name : 'sub-route-one',
          label : 'Sub Route One',
          path : 'sub-route-one',
          element : <SubRouteOne />,
        },
      ],
      {
        path : '/:id',
        routes : [
          {
            name : 'route-two',
            label : 'Route Two',
            element : <RouteTwo />,
            index : true,
          },
          {
            name : 'sub-route-two',
            label : 'Sub Route Two',
            path : 'sub-route-two',
            element : <SubRouteTwo />,
          },
        ],
      },
    }
  ]);

  return (
    <BrowserRouter>
      <MappingProvider routes={mapRoutes}>
        <Routes>
          {MainRoutes}
        </Routes>
      </MappingProvider>
    </BrowserRouter>
  );
};

With multiple maps

import React from 'react';
import { BrowserRouter, Routes } from 'react-router-dom';
import { MappingProvider, useMap } from 'react-router-mapping';

export default () => {

  const [ MainRoutes, mapRoutes ] = useMap([
    ...
  ]);

  const [ OtherRoutes, otherMapRoutes ] = useMap([
    ...
  ]);

  return (
    <BrowserRouter>
      <MappingProvider routes={[ mapRoutes, otlherMapRoutes ]}>
        <Routes>
          {MainRoutes}
          {OtherRoutes}
        </Routes>
      </MappingProvider>
    </BrowserRouter>
  );
};

For security, routes containing * are not added to the Map constructor returned by the useMap hook. This can confuse the breadcrumb hook.

Components

MappingProvider (Required)

Responsible for the functional context of the library, without it, any and all functionality will be invalid.

Properties

| Property | Type | Description | Default | | ------ | ------ | ------ | ------ | | routes | Object/Array | Receives an object or an array of Map objects, which is created by the useMap hook, which contains the handled routes to be served by the context. | Required |

Hooks

useMap() (Required)

Is the main hook for the proper functioning of the library. It takes only a single argument in its use, an array of objects, where any and all properties are the same as the Route component of the React Router. However, there are 2 new properties to be included that are necessary for the use of the other hooks that will be described later. Its return is an object with each of the routes informed in its argument, each property returned is equivalent to each of the routes informed and all already treated with the Route component.

Properties

| Property | Type | Description | Default | | ------ | ------ | ------ | ------ | | name | String | Key value for route identification | Required | | label | String | Friendly title for breadcrumb use | Empty |

useRoute()

Is the hook responsible for allowing you to access the routes object generated by the library. Below I describe their methods:

all()

This method returns a list with all the routes that the application has, for example:

import { useEffect } from 'react';
import { useRoute } from 'react-router-mapping';

export default () => {

  const { all } = useRoute();
	
  useEffect(() => {
    console.log(all());
  }, []);
  ...
}

Return

{
  "home": {
    "name": "home",
    "path": "/",
    "label": "Home"
  },
  "route-one": {
    "name": "route-one",
    "path": "/route-one",
    "label": "Route One"
  },
  "sub-route-one": {
    "name": "sub-route-one",
    "path": "/route-one/sub-route-one",
    "label": "Sub Route One"
  },
  "route-two": {
    "name": "route-two",
    "path": "/:id/route-two",
    "label": "Route Two"
  },
  "sub-route-two": {
    "name": "sub-route-two",
    "path": "/:id/route-two/sub-route-two",
    "label": "Sub Route Two"
  },
}

route(name:string, params:object)

This method has 2 (two) distinct features, the first would be passing a value to the first name argument, see below for a practical example:

import { useEffect } from 'react';
import { useRoute } from 'react-router-mapping';

export default () => {

  const { route } = useRoute();

  useEffect(() => {
    console.log(route('sub-route-one'));
  }, []);
  ...
}

Return

/route-one/sub-route-one

The second and last feature would be a complement to dynamic parameters in the route, to perform a substitution of values ​​in the routes, just use the second argument params as an object and put the property with the name of the desired parameter and its respective value, see the example:

import { useEffect } from 'react';
import { useRoute } from 'react-router-mapping';

export default () => {

  const { route } = useRoute();

  useEffect(() => {
    console.log('Without params: ', route('sub-route-two'));
    console.log('With params: ', route('sub-route-two', { id : 'DEF-456' }));
  }, []);
  ...
}

Return

Without params: /ABC-123/route-two/sub-route-two
...
With params: /DEF-456/route-two/sub-route-two

useBreadcrumb()

As the name says, this is a hook for breadcrump, without much secret, it returns an array of objects containing the full path of the user's location in the application, a practical example, let's say the user is on the 'Nested Route':

import { useEffect } from 'react';
import { useBreadcrumb } from 'react-router-mapping';

export default () => {

  const breadcrumb = useBreadcrumb();

  useEffect(() => {
    console.log(breadcrumb);
  }, []);
  ...
}

Return

[
  {
    "name": "home",
    "path": "/",
    "label": "Home",
  },
  {
    "name": "route-one",
    "path": "/route-one",
    "label": "Route One"
  },
  {
    "name": "sub-route-one",
    "path": "/route-one/sub-route-one",
    "label": "Sub Route One"
  }
]