Developers
Apollo Client Guide

Small Example: Snack

A tiny app that implements one view from our GitHunt example app, that you can run and edit right from your browser.
Edit on GitHub

The easiest way to see what Apollo Client and GraphQL can do for you is to try them for yourself. Below is a simple example of a single React Native view that uses Apollo Client to talk to our hosted example app, GitHunt. We’ve embedded it in the page with the Snack editor from Expo.

To start, let’s run the app. There are two ways:

  1. Click the “Tap to Play” button to run the app in the simulator.
  2. Open the editor in a new window and install the Expo app to run it on your iOS or Android device.

Either way, the app will automatically reload as you type.

First edit

Fortunately, the app is set up for us to make our first code change. Hopefully, after launching the app you see a view with a scrollable list of some GitHub repositories. This is fetched from the server using a GraphQL query. Let’s edit the query by removing the # in front of stargazers_count, so that the app also loads the number of stars from GitHub. The query should now look like this:

1
2
3
4
5
6
7
8
9
10
11
12
{
  feed (type: TOP, limit: 10) {
    repository {
      name, owner { login }
      # Uncomment the line below to get number of stars!
      stargazers_count
    }
    postedBy { login }
  }
}

Because in this example we’ve developed the UI in such a way that it knows how to display that new information, you should see the app refresh and show the number of GitHub stars from each repository!

Multiple backends

One of the coolest things about GraphQL is that it can be an abstraction layer on top of multiple backends. The query you did above is actually loading from two totally separate data sources at once: A PostgreSQL database that stores the list of submissions, and the GitHub REST API to fetch the information about the actual repositories.

Let’s verify that the app is actually reading from GitHub. Pick one of the repositories in the list, for example apollographql/apollo-client or facebook/graphql, and star it. Then, pull down the list in the app to refresh. You should see the number change! That’s because our GraphQL server is fetching from the real GitHub API every time, with some nice caching and ETag handling to avoid hitting a rate limit.

Explaining the code

Before you go off and build your own awesome GraphQL app with Apollo, let’s take a look at the code in this simple example.

This bit of code uses the graphql higher-order component from react-apollo to attach a GraphQL query result to the Feed component:

1
2
3
4
5
6
7
8
9
10
11
12
const FeedWithData = graphql(gql`{
  feed (type: TOP, limit: 10) {
    repository {
      name, owner { login }
      # Uncomment the line below to get number of stars!
      # stargazers_count
    }
    postedBy { login }
  }
}`, { options: { notifyOnNetworkStatusChange: true } })(Feed);

This is the main App component that React Native is rendering. It creates an Apollo Link with the server URL, initializes an instance of ApolloClient, and attaches that to our React component tree with ApolloProvider. If you’ve used Redux, this should be familiar, since it’s similar to how the Redux provider works.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
export default class App {
  createClient() {
    // Initialize Apollo Client with URL to our server
    return new ApolloClient({
      link: createHttpLink({
        uri: 'http://api.githunt.com/graphql',
      }),
      cache: new InMemoryCache()
    });
  }
  render() {
    return (
      // Feed the client instance into your React component tree
      <ApolloProvider client={this.createClient()}>
        <FeedWithData />
      </ApolloProvider>
    );
  }
}

Next, we get to a component that is actually dealing with some data loading concerns. Mostly, this is just passing through the data prop down to FeedList, which will actually display the items. But there is also an interesting React Native RefreshControl component here, which uses the built-in data.refetch method from Apollo to refetch data when you pull down the list. It also uses the data.networkStatus prop to display the correct loading state, which Apollo tracks for us.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// The data prop here comes from the Apollo HoC. It has the data
// we asked for, and also useful methods like refetch().
function Feed({ data }) {
  return (
    <ScrollView style={styles.container} refreshControl={
      // This enables the pull-to-refresh functionality
      <RefreshControl
        refreshing={data.networkStatus === 4}
        onRefresh={data.refetch}
      />
    }>
      <Text style={styles.title}>GitHunt</Text>
      <FeedList data={data} />
      <Text style={styles.fullApp}>See the full app at www.githunt.com</Text>
      <Button
        buttonStyle={styles.learnMore}
        onPress={goToApolloWebsite}
        icon={{name: 'code'}}
        raised
        backgroundColor="#22A699"
        title="Learn more about Apollo"
      />
    </ScrollView>
  );
}

Finally, we get to the place that actually displays the items, the FeedList component. This consumes the data prop from Apollo, and maps over it to display list items. You can see that thanks to GraphQL, we got the data in exactly the shape that we expected.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
function FeedList({ data }) {
  if (data.networkStatus === 1) {
    return <ActivityIndicator style={styles.loading} />;
  }
  if (data.error) {
    return <Text>Error! {data.error.message}</Text>;
  }
  return (
    <List containerStyle={styles.list}>
      { data.feed.map((item) => {
          const badge = item.repository.stargazers_count && {
            value: `☆ ${item.repository.stargazers_count}`,
            badgeContainerStyle: { right: 10, backgroundColor: '#56579B' },
            badgeTextStyle: { fontSize: 12 },
          };
          return <ListItem
            hideChevron
            title={`${item.repository.owner.login}/${item.repository.name}`}
            subtitle={`Posted by ${item.postedBy.login}`}
            badge={badge}
          />;
        }
      ) }
    </List>
  )
}

Now you’ve seen all of the code you need to build a React Native app that loads a list of items and displays it in a list with pull-to-refresh functionality. As you can see, we had to write very little data loading code! We think that Apollo and GraphQL can help data loading get out of your way so you can build apps faster than ever before.

Next steps

Let’s get you building your own app from scratch! You have two tutorials to go through, and we recommend doing them in the following order:

  1. Full-Stack GraphQL + React tutorial by Jonas Helfer.
  2. How to GraphQL by the team and community around Graphcool, a hosted GraphQL backend platform.

Have fun!

Edit on GitHub