redux-load-data v0.0.2

Redux LoadData

A React utility component that automatically fetches data from a JSON endpoint and stores it in with Immutable.js in a Redux data store.

This component is in Alpha release, so it may change significantly in new releases and shouldn't be depended on in production applications.

Introduction

One of the biggest challenges when developing a large React application that fetches data from a large number of endpoints is managing the data that comes from the backend API. While the Flux architecture and Redux in particular provide a great solution for structuring data; fetching data from an API, storing it in the Redux store and clearing it from memory when no longer needed are all tasks that still require a large amount of boilerplate code.

While there are several great libraries for handling async actions in Redux (such as redux-thunk & redux-saga), they provide a very generic way of handling asynchronous actions and developers still need to add code to fetch data from the API, store it in the Redux store and clear it when finished.

What this module does is provide a simple React component that will handle the lifecycle of fetched data with it's own component lifecycle by automatically fetching when mounted and clearing when unmounted. Since it doesn't require any custom redux middleware to function it can be easily used in any React/Redux application without.

Example

import { connect } from 'react-redux';
import LoadData from 'redux-load-data';

const QuoteOfTheDay = ({ quote, loading }) =>
  <div>
    <LoadData url="http://ron-swanson-quotes.herokuapp.com/v2/quotes" keyPath={['qotd']} />
    {loading ?
      <p>Loading...</p>
    :
      <p>{quote}</p>
    }
  </div>;

const mapStateToProps = (state) => ({
  quote: state.data.getIn(['qotd', 'data']),
  loading: state.data.getIn(['qotd', 'loading']),
})

export default connect(mapStateToProps)(QuoteOfTheDay)

Installation

Install the package from NPM with either

yarn add redux-load-data OR npm install --save redux-load-data

To use the component you simply need to include the dataReducer in your code as follows:

import { combineReducers } from 'redux';
import { dataReducer } from 'redux-load-data';

export default combineReducers({
  // ...All of the reducers you use in your app
  data: dataReducer
})

It is also possible to combine this with your own reducers if you wish, you simply need to expose reducers for the request, response, error and clear actions that the component uses. Refer to src/reducer.js for more information

Usage

Once setup you can simply just include this component with the props detailed here:

<LoadData
  // URL to access, data is fetched whenever this changes
  url="http://example.com/api"

  // Fetch options such as headers, method, etc. Axios is used internally to fetch data, so refer to the axios documentation (https://github.com/mzabriskie/axios) for details on these properties
  options={{headers: {'x-api-key': 'SECRET KEY'}}}

  // Path you want to store the resulting data in the the redux tree
  keyPath={['data']}

  // Set to true if you don't want data to be cleared on unmount
  persistant

  // Function that transforms new data downloaded and allows combining
  // with existing data already in the tree
  transformData={(newData, existingData) => [...existingData, ...newData]}

  // If true, this property will print the JSON data returned directly using react-json-tree (https://github.com/alexkuz/react-json-tree). This can be very helpful for testing and debugging an endpoint
  debug

  // The key name of the object where you store data, as well as the action names used by this component can all be configured as props. If you wish to use values other than the defaults you should set them here.
  reduxRoot: 'data',
  requestAction: 'DATA_REQUEST',
  responseAction: 'DATA_RESPONSE',
  errorAction: 'DATA_ERROR',
  clearAction: 'DATA_CLEAR',
/>

The structure returned from the default reducers is quite simple, and very closely matches the response returned by Axios. The default reducers included only set 2 extra booleans:

• loading: Set when the request action is fired and cleared on response or errorAction.
• error: Set when an error occurs and is reset when cleared or if new data is requested.