holocron-module-route

    1.2.0 • Public • Published

    Holocron Module Route - One Amex

    npm

    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

    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

    Install

    npm i holocron-module-route

    DownloadsWeekly Downloads

    425

    Version

    1.2.0

    License

    Apache-2.0

    Unpacked Size

    46.4 kB

    Total Files

    12

    Last publish

    Collaborators

    • amexopensource
    • 10xlacroixdrinker