holocron-module-route

This uses @americanexpress/one-app-router which is a fork of react-router@3. It extends its Route component which uses holocron's loadModule to dynamically load modules for specified routes.

In createModuleRoute, we check for the moduleName prop from the ModuleRoute. If moduleName exists, we define methods we know @americanexpress/one-app-router will leverage during the initialization of routes in the router.

If moduleName exists, createModuleRoute will add the methods for getIndexRoute, getChildRoutes, and getComponent to the that route in the route configuration.

📖 Table of Contents

• Usage
• API
• Available Scripts

🤹‍ Usage

Installation

yarn add holocron-module-route

# or

npm install --save holocron-module-route

Usage within your module

Register child routes by adding the property childRoutes to the container component of your Module.

src/components/MyModule.jsx

import React from 'react';

import childRoutes from '../childRoutes';

function MyModule({ children }) {
  return <div>{children}</div>;
}

MyModule.childRoutes = childRoutes;

export default MyModule;

Child routes

Define your child routes as either a single route, an array of routes or a function that takes the redux store and returns a single route or an array of routes.

src/childRoutes.jsx

import React from 'react';
import ModuleRoute from 'holocron-module-route';

export default function getChildRoutes(store) {
  return (
    <ModuleRoute
      path="my-child-route"
      moduleName="my-child-route-module"
      onEnter={(nextState, replace, callback) => {
        // this is just an example, not really how auth works :P
        !store.getState.isLoggedIn && replace('/login');
        callback();
      }}
    />
  );
}

🎛️ API

ModuleRoute

ModuleRoute extends one-app-router's Route. It has all the functionality of Route, with the addition of loading a holocron module instead of a component.

Extended Route Props

name	type	required	value
moduleName	String	false	The name of the Holocron module to render when the route is matched

Usage

const myRoutes = [
  <ModuleRoute path="some-path" moduleName="someModule" />,
];

Module Lifecycle Hooks

These are a few statics that can be attached to modules loaded as ModuleRoutes.

childRoutes

While child routes can be defined by nesting, frequently a module will need to load its own child routes rather than relying on its parent to define them.

childRoutes can be an array of routes, a single route, or a function that accepts the Redux store as a single parameter and returns either an array of routes or a single route.

As an Array:

const MyModule = () => { /* jsx */ };

MyModule.childRoutes = [
  <ModuleRoute path="some-path" moduleName="someModule" />,
  <ModuleRoute path="another-path" moduleName="anotherModule" />,
];

As a single route:

const MyModule = () => { /* jsx */ };

MyModule.childRoutes = <ModuleRoute path="some-path" moduleName="someModule" />;

As a function:

Arguments

name	type	value
store	Object	Redux store

Usage:

const MyModule = () => { /* jsx */ };

MyModule.childRoutes = (store) => (
  <ModuleRoute
    path="some-path"
    title={store.getState().get('pageTitle')}
    onEnter={authenticate}
    moduleName="someModule"
  />
);

onEnterRouteHook

When setting ModuleRoutes, you may set an onEnter hook as a prop on the <ModuleRoute /> itself. However, it is often useful for the module being loded to define its on onEnter hook. We can do so via onEnterRouteHook. onEnterRouteHook can take one, two, or three arguments, with different behavior for each.

One Argument

When using only one argument, onEnterRouteHook will receive the Redux store an must return an onEnter hook, which has the same API as defined in one-app-router.

name	type	value
store	Object	Redux store

Two or Three Arguments

When using two or three arguments, the API is the same as the onEnter in one-app-router, where the first two arguments are nextState and replace and the optional third argument is a callback, which, when used, will block the transition until it is called. See the one-app-router documentation for more details.

name	type	value
nextState	Object	Next router state
replace	Function	Redirects to another path
callback	Function	Blocks route transition until called

Usage

const MyModule = () => { /* jsx */ };

MyModule.onEnterRouteHook = (store) => (nextState, replace, callback) => {
  store.dispatch(authenticate()).then(() => {
    if (!store.getState().isAuthenticated) replace('/login');
    callback();
  });
};

moduleRoutePrefetch

moduleRoutePrefetch can be used to prefetch the modules and data for any route. It is a Redux Thunk action creator.

Arguments

name	type	required	value
routes	Object	true	Routes as given by one-app-router to its routes
location	String	true	Route to be prefetched

Usage

const PrefetchLink = ({ routes, location, prefetch }) => (
  <Link to={location} onMouseOver={() => prefetch(location)}>
    { children }
  </Link>
);

const mapDispatchToProps = (dispatch, { router: { routes } = { routes: [] } }) => ({
  prefetch: (location) => dispatch(moduleRoutePrefetch({ location, routes })),
});

export default connect(null, mapDispatchToProps)(PrefetchLink);

📜 Available Scripts

To test out any changes that you've made locally, run yarn pack then install this within your application.

The scripts below are available to run and use:

yarn babel

This deletes the current JS files within the lib directory and compiles the ECMAScript 6 code within the src file to a version of ECMAScript that can run in current browsers using Babel afterwards it copies them to the lib folder.

yarn build

This runs yarn babel

yarn prepublish

This runs yarn build