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.

🤹‍ Usage

Installation

yarn add holocron-module-route

# or

npm install --save holocron-module-route

Usage within 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