react-controller

react-controller is a component for React that takes a path, fetches a JSON response, and passes the object to its child component. Page caching, custom loading screens, prefetching and server-side rendering are made incredibly easy, especially when paired with react-router.

Installation

$ npm i react-controller --save

import Controller from 'react-controller'

The UMD build is also available on unpkg:

<script src="https://unpkg.com/react-controller/umd/react-controller.min.js"></script>

When using the UMD build, you can find the library on window.ReactController.

Basic Usage

This simplified example will make an XHR request to /api/product/foo-bar and pass the resulting JSON object to the Child component. Until the request is returned, the ProductLoading component will be rendered.

<Controller path="/api/product/foo-bar" loadingComponent={ProductLoading}>
  <Product />
</Controller>

Props

• path string (Required)
  The endpoint to request data from.

• children function or ReactElement (Required)
  Can be either a typical React element or a function.

• cache boolean (Default: false)
  Setting to true will store all previously requested path data in the Controller state.

• initialProps object (Default: null)
  If the app is server rendered, pass the in initialProps to avoid an extra XHR request when the Controller component mounts.

• loadingComponent function (Default: null)
  The React component that should render while the requested path is loading.

• onError function
  A function that will be called if the requested path returns anything other than a 200 header.

• forceReload boolean (Default: false)
  If cache is turned on, but a certain path should always make an XHR request to the server, set forceReload to true.

• isStatic boolean (Default: false)
  If the child component doesn’t need to make an XHR request to the server to render, then set isStatic to true.

• options object (Default: {})
  Object containing parameters for the request. (See the fetch spec.)

Handling Errors

There are two different ways to handle errors. The first is to pass a function into the onError prop of the Controller component. If no error occurs, then the object returned from your path will be spread across your child component's props.

import React from 'react'
import Controller from 'react-controller'
 
const ErrorHandler = ({ status }) => (
  <div>{status} status header.</div>
)
 
const App = () => (
  <Controller path="/api/product/foo-bar" onError={ErrorHandler}>
    <Product />
  </Controller>
)
 

The second, option is to pass a function as the children prop of Controller. This allows you to choose to pass only specific parts of the returned object.

import React from 'react'
import Controller from 'react-controller'
 
const ErrorHandler = ({ status }) => (
  <div>{status} status header.</div>
)
 
const App = () => (
  <Controller path="/api/product/foo-bar">
    {(error, props) => error ? (
      <ErrorHandler status={error.status} />
    ) : (
      <Product {...props} />
    )}
  </Controller>
)

Prefetching

If you would like to prefetch a page, use the this.context.controller.prefetch() function.

import React, { Component } from 'react'
import PropTypes from 'prop-types'
 
class Homepage extends Component {
  static contextTypes = {
    controller: PropTypes.object.isRequired
  }
 
  componentDidMount() {   
    this.context.controller.prefetch('/products')
  }
 
  ...
}

Example

To run the example application, run these commands from inside the /example directory.

$ npm i
$ npm start

View the example at http://localhost:3000.