Your React Native offline toolkit

I gotta say I am quite new to the world of open source. I was always afraid of contributing due to my lack of experience in following the typical OS workflow. It felt like a steep mountain to climb. Much less did I think about writing my own library, but one day you decide to take your mountain equipment, join this awesome community and give back.

The problem

Having worked with React for a while, I am currently building a medium-sized React Native application in my free time, simply to try out the platform and because I truly love building mobile apps with minimum effort. Mobile apps require you to cover things that may be easily overlooked if you are even a bit careless.

One of the expectations is that some users may use your application in offline mode. How does your app behave when a user is travelling on a plane (airplane mode) or the underground (no signal)? Does it show an infinite loader? Can the user still use the app seamlessly?

Having an offline first-class citizen app is very important for a great user experience. You may have heard about (or used) NetInfo module, which comes shipped in with React Native and provides a handful of methods to get the network connection status on the device. The API is pretty basic, and it may be sufficient for small apps but its usage gets cumbersome as your app grows.

When that happens, you'll find yourself repeating code in the two following scenarios:

• Inside Component's render: rendering one thing or another depending on whether I have internet connection or not
• Inside your business logic: grabbing connection state and conditionally fetching data

Besides that, NetInfo presents another downside. Its API allows you to detect network connectivity, but it does not guarantee you can exchange data with a remote server even though it reports you are connected. This scenario could occur inside an airport where there are a lot of available networks that you could connect to, though forcing you to go through an extra step (like filling a form) in order to gain internet access.

As I was trying to find a more compact solution to this problem, react-native-offline was born. I'll elaborate on the different parts of the library in the context of the app I was building.

Component Utilities

There are occasions when you would want to hide or change content on the screen depending on whether there is internet connection or not. Let's analyze a couple of examples based on an event's app.

Let's say we would like to know all the events for a particular day. If there is no internet connection, we will instead show to the user a text message stating we are in offline mode. In this case, the library provides you with a Higher Order Component utility that passes the connection state down as a prop. You'd use it the following way:

import React from "react";
import { withNetworkConnectivity } from "react-native-offline";
import { View, Text } from "react-native";
import EventList from "./EventList";

const EventsForDay = ({ isConnected, day }) => (
  <View style={{ flex: 1 }}>
    {isConnected ? <EventList day={day} /> : <Text>We are offline :(</Text>}
  </View>
);

export default withNetworkConnectivity()(EventsForDay);

Let’s think now of a slightly different scenario. Imagine an events detail page where you can rsvp and also check the event location through a map. In case of a lack of connection and assuming we are persisting our data, the user should still be able to check event details, but we’d like to tweak the screen content a bit by preventing the user from performing network dependent actions.

In this case, our goal is to disable the rsvp buttons, hide the map (assuming we have a service to get the geolocation coordinates based on the address) and, in addition, show a SnackBar at the bottom to inform the user that some functionalities on that screen may be disabled.

If we wanna keep the rendering of the screen in one file, a Higher Order Component won’t work. In such a case the library provides a Function as a Child Component (a.k.a render prop) as a convenience.

import React, { Component } from "react";
import { View, ScrollView } from "react-native";
import { ConnectivityRenderer } from "react-native-offline";
// Rest of component imports ...

class EventDetailsScreen extends Component {
  render() {
    const { event } = this.props;
    return (
      <ScrollView style={styles.container}>
        <EventCover uri={event.uri} />
        <View style={styles.content}>
          <EventBasicInformation data={event.basicInfo} />
          <ConnectivityRenderer>
            {(isConnected) =>
              isConnected && (
                <EventLocation
                  address={event.fullAddress}
                  eventId={event.eventId}
                />
              )
            }
          </ConnectivityRenderer>
          <EventDescription description={event.description} />
          <ConnectivityRenderer>
            {(isConnected) => <RsvpButtons disabled={!isConnected} />}
          </ConnectivityRenderer>
        </View>
        <ConnectivityRenderer>
          {(isConnected) => (
            <SnackBar
              message="You are currently offline, some features may be disabled"
              predicate={!isConnected}
            />
          )}
        </ConnectivityRenderer>
      </ScrollView>
    );
  }
}

export default EventDetailsScreen;

You should take into account that since ConnectivityRenderer gives you this power at render time, you typically can’t optimize them using shouldComponentUpdate without hindering your composition ability, so it’s recommended to use it on leaf components in your tree.

Redux integration

For medium and large apps redux is by far the current de facto solution for managing your application state. The library provides a nice integration, by offering three features that leverage offline capabilities in your redux store: a reducer, a middleware and an offline queue system. You can use all of them or just the ones that suits your needs.

Reducer

It allows you to centralize the connection status in your redux store. Basically it supplies a network reducer that listens to internal actions dispatched when the connection status changes. The configuration is pretty straightforward, and you can check it out in the documentation.

Middleware

Before diving in, let me provide you with a bit of context. In my application I chose redux-saga as the library for managing side effects and network calls and I got to the point where I had around 20 sagas with the following pattern:

import NetInfo from "react-native";
import { call, put, select, fork, takeEvery } from "redux-saga";
import * as actions from "./actions";
import api from "./api";

function* fetchData({ payload }) {
  const isConnected = yield call([NetInfo, NetInfo.isConnected.fetch]);
  if (isConnected) {
    const accessToken = yield select(accessTokenSelector);
    try {
      const { data } = yield call(api.fetchData, accessToken, payload.params);
      yield put(actions.fetchDataSuccess(data));
    } catch (error) {
      yield put(
        actions.fetchDataError({
          errorType: "server",
        })
      );
    }
  } else {
    yield put(
      actions.fetchDataError({
        errorType: "offline",
      })
    );
  }
}

export default function* watchFetchData() {
  yield fork(takeEvery, "FETCH_DATA_REQUEST", fetchData);
}

Do you see the repetitive parts? It boils down to grabbing the connection state, the if/else structure for fetching data and dispatching a specific action to handle the offline situation. I live with DRY in mind, so that was annoying me. How could we get rid of that repetition? You guessed it, redux middleware to the rescue.

Redux middleware is the game changer that allows you to place code that sits in between your dispatched actions and the moment they reach the reducer. It’s the perfect place to anticipate the loss of connection and prevent the action from going through the reducer. That way, we have that logic defined in one place only and can clean up a bit our side effects code.

The API exposes a function, createNetworkMiddleware, that returns a redux middleware which you can later apply using applyMiddleware utility from redux:

import type { ReduxMiddleware } from "redux";

type Config = {
  regexActionType?: RegExp;
  actionTypes?: string[];
};

function createNetworkMiddleware({
  regexActionType = /FETCH.*REQUEST/,
  actionTypes = [],
}: Config): ReduxMiddleware;

All parameters are optional and, by default, it will look at your fetch actions types following the redux convention, but you can either provide your own regular expressions and/or any additional action types involving a network call that you are interested to observe. To do that you can use theactionTypes parameter and set it to, for example, AUTHORISE_USER or RELOAD_LIST.

For thunks, the configuration differs. First, you need to make sure of using a named function declaration instead of an anonymous arrow function. Lastly, set interceptInOffline property to true in your thunk as you can see in the below example:

export const fetchUser = (url) => {
  return function thunk(dispatch) {
    fetch(url)
      .then((response) => response.json())
      .then((responseJson) => {
        dispatch({ type: "FETCH_USER_SUCCESS", payload: responseJson });
      })
      .catch((error) => {
        console.error(error);
      });
  };

  thunk.interceptInOffline = true;
};

If we attempt to fetch internet resources and happen to be offline, the middleware will stop and prevent the action from going through the rest of the middleware chain, dispatching instead an action of type @@network-connectivity/FETCH_OFFLINE_MODE whose payload contains useful information about “what you attempted to do”.

With this middleware applied to redux, the previous saga would result in:

function* fetchData({ payload }) {
  const accessToken = yield select(accessTokenSelector);
  try {
    const { data } = yield call(api.fetchData, accessToken, payload.params);
    yield put(actions.fetchDataSuccess(events));
  } catch (error) {
    yield put(actions.fetchDataError(error));
  }
}

Isn’t that neat? :) Now you just have to import that action type from the library and listen to it inside your reducers.

Worth saying that the same reduction of code would apply to libraries such as redux-observable or redux-thunk.

Offline queue

Last but not least, the middleware interoperates with an offline queue in order to keep track of actions that failed to be dispatched due to the lack of connection. There are two possible configurations:

• Retry an action
• Dismiss an action from the queue based on a different action dispatched

To enable queuing in your redux actions you need to use the meta property, which provides retry and dismiss options.

type ActionToBeQueued = {
  type: string;
  payload?: any;
  meta: {
    retry?: boolean;
    dismiss?: Array<string>;
  };
};

If you set retry: true, the action will be added to the queue and will be automatically re-dispatched when the connection is back again.

However, there are cases where the action queued is no longer relevant. One scenario is navigation actions that involve replacing the entire screen content. For that, the dismiss option is quite handy, and you can use it to provide an array of action types that, in case of being dispatched, will dismiss and remove the queued action.

Detecting Internet access

We stated before that NetInfo carried the limitation of being only able to detect network connectivity, lacking a way to determine whether we have internet access or not.

To solve that problem, the library takes a step further and covers the ground by pinging a remote server using a http HEAD request, in order to make sure the new connection state is not a false positive. By default, it’s configured to ping google.com with a timeout of 3 seconds, but you can customise both remote server and timeout as you wish. Those parameters can be passed to component utilities and your redux store.

Wrapping up

It’s been a pleasant journey to shape up my first open source library, and I am happy to see that other people use it in their projects too. Following the best practices, the library has also almost 100% test coverage in the business logic and is fully typed with Typescript. The README.md contains all the instructions to set up the library, full API documentation and some useful examples.

react-native-offline

If you found this article useful, follow me on Twitter @rgommezz for React Native updates and more content like this.

Happy coding! ❤️