Non-Partisan Magicians

    react-router-redial

    0.3.6 • Public • Published

    react-router-redial Travis npm package Coveralls

    Simple integration of redial for React Router

    $ npm install --save react-router-redial redial

    Why?

    Data fetching is an important part of applications and redial is a great way to manage this in React when using React Router. This project aims to provide a great way to use redial together with React Router with a simple but yet powerful API.

    Additionally it offers an alternative way to manage data for components without the need of flux. This means that you can start creating an application without for instance Redux and when you see the need for it you can easily update your application gradually.

    react-router-redial has been inspired by AsyncProps and can be seen as an alternative to it.

    Works with universal applications that run on the server and the client as well as client only applications.

    Works with IE9 if a Promise polyfill is provided.

    Difference from redial

    • Simple integration with React Router
    • Managing client side data loading with route transition support
    • Powerful API to control hooks on both client and server
    • Alternative way to pass data to components without the need of Redux

    Difference from AsyncProps

    • Uses redial hooks to manage data loading
    • Possible to easily transition to Flux/Redux

    Lifecycle hooks

    You use @provideHooks as would normally when using redial. One difference is that react-router-redial will provide some default locals to the hooks.

    import { provideHooks } from 'redial';
     
    import React, { Component } from 'react';
    import { getSomething } from 'actions/things';
     
    @provideHooks({
      fetch: ({ dispatch, params: { id } }) => dispatch(getSomething(id)),
      defer: ({ setProps, getProps, force }) => {
        const { data } = getProps();
        if(!data || force) {
          // Will be available as this.props.data on the component
          setProps({ data: 'My important data' })
        }
      }
    })
    class MyRouteHandler extends Component {
      render() {
        return <div>{ this.props.data }</div>;
      }
    }

    Default locals provided to the hooks

    setProps          Makes it possible to set things that should be available to the component as props, should be an object
    getProps          Makes it possible to get things that has been defined for the component, can be used for bailout
    force             If the provideHooks has been invoked using the reload function
    params            Route params from React Router
    location          Location object from React Router
    routeProps        Custom defined properties that has been defined on the route components
    isAborted         Function that returns if the hooks has been aborted, can be used to ignore the result
    

    Default props available to decorated components

    loading                 Will be true when beforeTransition hooks are not yet completed
    afterTransitionLoading  Will be true when afterTransition hooks are not yet completed
    reload                  Function that can be invoked to re-trigger the hooks for the current component
    abort                   Function that can be invoked to abort current running hooks
    

    Additionally components will have access to properties that has been set using setProps.

    Client API

    The custom redial router middleware useRedial makes it easy to add support for redial on the client side using the render property from Router in React Router. It provides the following properties as a way to configure how the data loading should behave.

    locals                     Extra locals that should be provided to the hooks other than the default ones
    beforeTransition           Hooks that should be completed before a route transition is completed
    afterTransition            Hooks that are not needed before making a route transition
    parallel                   If set to true the afterTransition hooks will run in parallel with the beforeTransition ones
    initialLoading             Component should be shown on initial client load, useful if server rendering is not used
    onStarted(force)           Invoked when a route transition has been detected and when redial hooks will be invoked
    onError(error, metaData)   Invoked when an error happens, see below for more info
    onAborted(becauseError)    Invoked if it was prematurely aborted through manual interaction or an error
    onCompleted(type)          Invoked if everything was completed successfully, with type being either "beforeTransition" or "afterTransition"
    

    onError(error, metaData)

    metaData

    abort()            Function that can be used to abort current loading    
    beforeTransition   If the error originated from a beforeTransition hook or not
    reason             The reason for the error, can be either a "location-changed", "aborted" or "other"
    router             React Router instance https://github.com/ReactTraining/react-router/blob/master/docs/API.md#contextrouter
    

    Example

    We can use onError to add handling for errors in our application. The example below shows how we can make the client either reload the page or transition back to the previous page on an error.

    const forcePageReloadOnError = true;
    const goBackOnError = false;
     
    // Function that can be used as a setting for useRedial
    function onError(err, { abort, beforeTransition, reason, router }) {
      if (process.env.NODE_ENV !== 'production') {
        console.error(reason, err);
      }
     
      // We only what to do this if it was a beforeTransition hook that failed
      if (beforeTransition) {
        if (forcePageReloadOnError && reason === 'other') {
          window.location.reload();
        } else if (goBackOnError && reason !== 'location-changed') {
          router.goBack();
        }
        // Abort current loading automatically
        abort();
      }
    }

    Example

    import { useRedial } from 'react-router-redial';
    import { applyRouterMiddleware } from 'react-router';
     
    <Router
      history={ browserHistory }
      routes={ routes }
      render={ applyRouterMiddleware(
        useRedial({
            locals,
            beforeTransition: ['fetch'],
            afterTransition: ['defer', 'done'],
            parallel: true,
            initialLoading: () => <div>Loading…</div>,
        })
      )}
    />

    Server API

    Instead of using trigger on the server side we will use a wrapper that provides additional functionally named triggerHooks. It takes an object as an argument that has the following properties that can be used to configure how the data loading should behave.

    components        The components that should be scanned for hooks, will default to renderProps.components
    renderProps       The renderProps argument that match from React Router has in the callback
    hooks             The hooks that should run on the server
    locals            Additional locals that should be provided over the default, useful for Redux integration for example
    

    triggerHooks will return a Promise that will resolve when all the hooks has been completed. It will be resolved with an object that contains the following properties.

    redialMap         This should be used together with RedialContext on the server side
    redialProps       This is for passing the props that has been defined with setProps to the client, expected to be on window.__REDIAL_PROPS__
    

    Example

    import { triggerHooks } from 'react-router-redial';
     
    const locals = {
      some: 'data',
      more: 'stuff'
    };
     
    triggerHooks({
      components,
      renderProps,
      hooks,
      locals
    }).then(({ redialMap, redialProps }) => render(redialMap, redialProps));

    Hooks

    react-router-redial provides a simple way to define in what order certain hooks should run and if they can run in parallel. The same syntax is used for both hooks when used on the server with triggerHooks and beforeTransition + afterTransition on the client with RedialContext. The hooks are expected to be an array the can contain either single hooks or arrays of hooks. Each individual element in the array will run in parallel and after it has been completed the next element will be managed. This means that you can run some hooks together and others after they have been completed. This is useful if you for instance want to run some hook that should have access to some data that other hooks before it should have defined.

    Example

    Let's look at an example to understand this a bit better. Say that we have the following hooks defined on the server:

    {
      hooks: [ ['fetch', 'defer'], 'done' ]
    }

    This means that the fetch and defer hooks will run at the same time and after they have been completed the done hook will run and it will then have access to the potential data that they might have set using either setProps or with for example Redux.

    Example

    Client

    import { useRedial } from 'react-router-redial';
     
    import React from 'react';
    import { render } from 'react-dom';
    import { Router, browserHistory, applyRouterMiddleware } from 'react-router';
    import { Provider } from 'react-redux';
     
    // Your app's routes:
    import routes from '../shared/routes';
     
    // Render the app client-side to a given container element:
    export default (container, store) => {
      // Define extra locals to be provided to all lifecycle hooks:
      const locals = store ? {
        dispatch: store.dispatch,
        getState: store.getState,
      } : {};
     
      let component = (
        <Router
          history={browserHistory}
          routes={routes}
          render={ applyRouterMiddleware(
            useRedial({
              locals,
              beforeTransition: ['fetch'],
              afterTransition: ['defer', 'done'],
              parallel: true,
              initialLoading: () => <div>Loading…</div>,
            })
          )}
        />
      );
     
      if (store) {
        component = (
          <Provider store={store}>
            {component}
          </Provider>
        );
      }
     
      // Render app to container element:
      render(component, container);
    };

    Server

    import { triggerHooks, useRedial } from 'react-router-redial';
     
    import React from 'react';
    import { renderToString } from 'react-dom/server';
    import { createMemoryHistory, match, applyRouterMiddleware } from 'react-router';
    import { Provider } from 'react-redux';
     
    // Your app's routes:
    import routes from '../shared/routes';
     
    // Render the app server-side for a given path:
    export default (path, store) => new Promise((resolve, reject) => {
      // Set up history for router:
      const history = createMemoryHistory(path);
     
      // Match routes based on history object:
      match({ routes, history }, (error, redirectLocation, renderProps) => {
     
        // Define extra locals to be provided to all lifecycle hooks:
        const locals = store ? {
          dispatch: store.dispatch,
          getState: store.getState
        } : {};
     
        // Wait for async data fetching to complete, then render:
        triggerHooks({
          renderProps,
          locals,
          hooks: [ 'fetch', 'done' ]
        }).then(({ redialMap, redialProps }) => {
          const state = store ? store.getState() : null;
          // Use `applyRouterMiddleware` to create the `<RouterContext/>`,
          // as well as the `<RedialContext/>` and `<RedialContextContainer/>`
          // around each matched route. Pass in the `redialMap` to the middleware
          // to ensure we have access to it while rendering, and
          // pass the renderProps provided from `match`
          const component = applyRouterMiddleware(useRedial({ redialMap }))(renderProps);
          const html = store ? renderToString(
            <Provider store={store}>
              { component }
            </Provider>
          ) : renderToString(component);
     
          // Important that the redialProps are sent to the client
          // by serializing it and setting it on window.__REDIAL_PROPS__
          resolve({ html, state, redialProps });
        })
        .catch(reject);
      });
    });

    Contributors

    Install

    npm i react-router-redial

    DownloadsWeekly Downloads

    11

    Version

    0.3.6

    License

    MIT

    Last publish

    Collaborators

    • dlmr