Real-World ReactJS and Redux (Part 1)

This is the first in a series of blog posts about real-world ReactJS usage and what we've learned scaling our apps at Threat Stack.

Real-world means we're concerned with answering the following:

• Can you darkship a feature?
• What is the ease of development?
• How fast can new team members understand what's going on?
• How fast can you figure out where something is broken?

And yes...because this is JS-land, there is probably a library for most techniques, that abstracts it all and injects tons of awesome magic.

Magic Doesn't Scale!

Consistent patterns do.

Consistent patterns, data structures, and appropriate tools will help you build your larger system.

Boilerplate code isn't the axis of all evil, and trying to remove it all will come at a price.

Scenario:

Dev needs to add a component that loads data from the server and updates the app.

Rules:

1. Don't make pointless requests to the server.
2. The code should be decoupled.
3. It should be visible, meaning that, if a dev asks:
   "Hey, where does this thing over here take place?"
   You should be able to point them at something searchable in the code.
4. A dev should be able to follow a pattern for something similar being done in the app.
5. And finally, it should be fully testable.

You do test all your data access points, amirite?! 

ItemActions.js

import Api from '../apis/ItemsApi';
import {
  REQ_ITEM,
  REQ_ITEM_SUCCESS,
  REQ_ITEM_ERROR
} from '../constants/ItemTypes';

/**
 * Returns an CallApiAction, which is an action expected to
 * be processed by the `CallApiMiddleware`
 * @param  {String} id
 * @return {CallApiAction}
 */
export function loadItemById ({ id }) {
  // cache timeout
  const TTL_MS = 1000 * 60 * 5;

  return {
    /**
     * types for this action - "request, success, error"
     * @type {Array}
     */
    types: [ REQ_ITEM, REQ_ITEM_SUCCESS, REQ_ITEM_ERROR ],

    /**
     * receives the current app state
     * and returns true if we should call the api
     *
     * @param  {AppState} state
     * @return {Bool}
     */
    shouldCallAPI: (state) => {
      const item     = state.items[id];
      const isCached = Date.now() - item.updatedAt < TTL_MS;

      // if we don't have the item or it's beyond the cache 
      // timeout make the api call
      return !item || !isCached;
    },

    /**
     * returns a function used to call the api
     * NOTE: we could've put the direct request call here
     * but that'll hurt our decoupling goals... gotta have goals
     * @return {Function}
     */
    callAPI: () => Api.getItemById({ id }),

    /**
     * This is a payload object to be sent along with the
     * actions (request, success, error)
     * some possible use cases:
     * - need a param sent in the request that isn't in the response
     * - pass along a previous state item and do optimistic updates
     * - timing or tracking params
     *
     * @type {Object}
     */
    payload: {
      requestId: id
    }
  };
}

We're using superagent.

But, the beauty in having a separate API library is that you can use whatever you want internally.

The action calls Api.getItemById()and expects a certain type of response.

Alter the underlying code as long as you maintain the contract.

Yup!Not a mind-blowing idea, but not easily seen in the wild. 

ItemApi.js

import request from 'superagent';

/**
 * Builds a `superagent` request object to get an item by Id
 * NOTE: we're only `building` and returning the object here. We're not firing
 * the request yet. The Middleware will handle that portion
 * @param  {String} id
 * @return {SuperAgent}
 */
getItemById ({ id }) {
  return (
    request
    .get(`/api/items/${id}`)
    .query({
      enabled: true
    })
  );
}

compoments/Item.react.js

// dispatch your call on mount
// since we have `shouldCallAPI` in place
// we don't need to worry about making pointless requests to the server 
// if we have more than one component on the page 
componentDidMount() {
  dispatch(loadItemById(this.props.itemId));
}

And now, the middleware to take care of this.

Super quick refresher on what middleware accomplishes:

loadItemById() -> code A -> middleware -> code C

You're intercepting a function call, doing things, and then letting it continue to the next call.

It's like checking your bags at the airport:
 
checkinAtAirport() -> terminalA() -> removeShampooFromBag() ->
arriveAtDestinationWithNoShampoo()

middlewares/CallApiMiddleware.js

export default function callAPIMiddleware ({ dispatch, getState }) {
  return next => action => {

    const {
      types,
      callAPI,
      shouldCallAPI = () => true,

      // used to pass remaining props from dispatch action along
      // `payload` in our case
      ...props
    } = action;

    // if we don't have the `types` prop
    // we're not supposed to intercept it with this middleware... move it along
    if (!types) {
      return next(action);
    }

    if (!Array.isArray(types) ||
        types.length !== 3 ||
        !types.every(type => typeof type === 'string')) {

      throw new Error('Expected an array of three string types.');
    }

    if (typeof callAPI !== 'function') {
      throw new Error('Expected callAPI to be a function.');
    }

    // If we shouldn't call the API, bail
    if (!shouldCallAPI(getState())) {
      return undefined;
    }

    // break out types in order by request, success and failure
    const [requestType, successType, failureType] = types;

    // dispatch the request action (`REQ_ITEM`)
    dispatch({
      ...props,
      type: requestType
    });

    const api = callAPI();

    // this assumes we're using `superagent` or anything
    // with an `end` function. If you wanted to change
    // the lib used for ajax requests, you could use whatever you
    // want in `Api.js` as long as you  return an `end` function
    // ...or use a new middleware of course
    // Either way, the code is decoupled and doesn't care 

    return api.end((err, resp) => {

      // we check for an error response 
      if (err || !resp.success) {

        // there was an error, dispatch `REQ_ITEM_ERROR`
        dispatch({
          ...props,
          type: failureType,
          err : err
        });

        return;
      }

      // success, dispatch `REQ_ITEM_SUCCESS`
      dispatch({
        ...props,
        type: successType,
        data : resp.data
      });
    });

  };
}

What Can Be Tested So Far?

• Requests that should be cached don't reach the API call.
• We're using the correct action types "REQ_ITEM" vs "REQ_JERRY".
• The API call will have the correct:
  • URL
  • Request method
  • Query params
  • Post body
  • Headers... all the things really

tests/ItemActions.test.js

describe('loadItemById', () => {
  const params = {
    id: 'foo-01'
  };

  let action;
  beforeEach(() => {
    action = actions.loadItemById(params);
  });

  it('should not callAPI if data is cached with TTL', () => {
    const cachedState = {
      items: {
        [params.id] : {
          updatedAt: Date.now() - 100
        }
      }
    };

    expect(action.shouldCallAPI(cachedState)).to.be.false;
  });

  it('should callAPI if data cache TTL is invalid', () => {
    const past = Date.now() - (1000 * 60 * 5) - 1;
    let state = {
      items: {
        [params.id] : {
          updatedAt: past
        }
      }
    };
    expect(action.shouldCallAPI(state)).to.be.true;

    state = {
      items: {}
    };

    expect(action.shouldCallAPI(state)).to.be.true;
  });

  it('should create a REQ_ITEM callAPI action', () => {

    expect(action.payload).to.deep.equal({
      id: params.id
    });

    expect(action.types).to.deep.equal([
      types.REQ_ITEM,
      types.REQ_ITEM_SUCCESS,
      types.REQ_ITEM_ERROR
    ]);

    const callAPI = action.callAPI().end(() => {});
    expect(callAPI.method).to.equal('GET');
    expect(callAPI.url).to.equal(`/api/items/${params.id}`);
    expect(callAPI.qs).to.deep.equal({
      enabled: true
    });
  });
});

In your reducer, adjust state, and you can also make use of the extra payload object.

itemReducer.js

export default function (state = initialState, action) {
  const { 
    data,    // data contains the response data from the server
    payload  // props that we wanted injected with each call
  } = action;

  switch (action.type) {
    case REQ_ITEM:
      return {
        ...state,
        [payload.id] : {
          data      : {},
          err       : null,
          isLoading : true
        }
      };

    case REQ_ITEM_SUCCESS:
      return {
        ...state,
        [payload.id] : {
          data      : data,
          err       : null,
          isLoading : false
        }
      };

    // because of `payload.id`, we're able to set things using the `id` in question. 
    // e.g: there was a 500 error and all you had was 
    //   the error message from the api response
    //   to set the error based on the id
    case REQ_ITEM_ERROR:
      return {
        ...state,
        [payload.id] : {
          data      : {},
          err       : action.err,
          isLoading : false
        }
      };

    default:
      return state;
    }
  }
}

Where We Ended Up...

• More data structures, declarative patterns, and less magic.  
• Tools to build your larger system that are easier to follow and debug. 

And speaking of debugging...

Bonus Round: Debugging!

There are several redux dev tools out there. I consider Redux Logger to be a must. It allows you to see on the console every redux action and current app state. In an app where state dictates UI instead of the random $('#foo').text('bar'), this becomes a great tool for debugging.

Use redux-logger.

Here's what it will look like:

This will show you prev State, action with the params, and next State. Awwww yeah!**

Scenarios:

Bug comes in, dev opens the console and sees each action happen...

"Whoa, state didn't get updated properly when I clicked to toggle this filter."

New dev joins:

• Opens console
• Loads page and gets a rough idea of actions that are happening. For example:
  • LOAD_USER_INFO
  • LOAD_USER_PHOTOS
  • UPDATE_FILTER

You'll want to enable this only in DEV though!

When configuring your store, you'll add the logger based on the NODE_ENV.

configureStore.js

const middleware = process.env.NODE_ENV === 'production'
  ? [ thunk ]
  : [ thunk, logger() ];

let createStoreWithMiddleware = applyMiddleware(...middleware)(createStore);

To benefit from that NODE_ENV parsing, you'll have to update your webpack config or use loose-envify in your build process.

webpack.config.js

new webpack.DefinePlugin({
  'process.env': {
    'NODE_ENV': JSON.stringify(env)
  }
})

or use https://github.com/zertosh/loose-envify

browserify index.js -t envify > bundle.js

What's Next...

Over the next couple of posts, I'll be going through patterns that have worked for us.

They're not perfect and are always evolving.

But they'll be following the rules of real-world dev.