While this tutorial has content that we believe is of great benefit to our community, we have not yet tested or edited it to ensure you have an error-free learning experience. It's on our list, and we're working on it! You can help us out by using the "report an issue" button at the bottom of the tutorial.

The Apollo GraphQL client is a very popular way to interface with a GraphQL API on the client-side. In this post we’ll go over how to setup Apollo in a React app using Apollo Boost and React Apollo 2.1.

What are these two for, you ask?

Apollo Boost : Setting up Apollo on the client used to require quite a lot of boilerplate code, and Apollo Boost fixes that. It’s a bundled combination of apollo-client , apollo-cache-inmemory , apollo-link-error , apollo-link-http and apollo-link-state that allows for a much easier setup.

: Setting up Apollo on the client used to require quite a lot of boilerplate code, and Apollo Boost fixes that. It’s a bundled combination of , , , and that allows for a much easier setup. React Apollo : A React-specific integration for Apollo. It provides us with a lot of goodies like the Query and Mutation components.

This tutorial assumes the use of React Apollo 2.1+

Installation

Let’s first initialize a React project using npx and Create React App:

$ npx create-react-app hello-graphql

You can then cd into the project and start a local dev server:

$ cd hello-graphql && yarn start

We’ll also need a few extra packages in our project, namely graphql, graphql-tag, apollo-boost and react-apollo. Add them using npm or Yarn:

$ yarn add graphql graphql-tag apollo-boost react-apollo # or, using npm: $ npm i graphql graphql-tag apollo-boost react-apollo

With our project in place and packages added, we can now setup the Apollo client.

Setup

The client setup couldn’t be easier. We’ll initiate a client and give it the URI to our GraphQL server endpoint and then use the ApolloProvider component to to make the client available in our app’s components.

For this example our endpoint will point to an Apollo Launchpad instance with data about Star Wars:

index.js

import React from 'react'; import ReactDOM from 'react-dom'; import { ApolloProvider } from 'react-apollo'; import { ApolloClient, HttpLink, InMemoryCache } from 'apollo-boost'; import './index.css'; import App from './App'; const client = new ApolloClient({ link: new HttpLink({ uri: 'https://mpjk0plp9.lp.gql.zone/graphql' }), cache: new InMemoryCache() }); const AppWithProvider = () => ( <ApolloProvider client={client}> <App /> </ApolloProvider> ); ReactDOM.render(<AppWithProvider />, document.getElementById('root'));

A few things to note:

We initialize the client with an HttpLink that points to our GraphQL endpoint and then also specify Apollo’s InMemoryCache as the caching utility.

that points to our GraphQL endpoint and then also specify Apollo’s InMemoryCache as the caching utility. We use the ApolloProvider component, pass it our client as prop and then wrap it around our App component.

Query Component Example

Now that everything’s in place, we can start running queries against the GraphQL endpoint. For this, we’ll use React Apollo’s Query component, which makes use of the render prop pattern to give us the data back from the query.

Here’s an example where we query for a Star Wars’ episode hero and his/her friends:

App.js

import React from 'react'; import PropTypes from 'prop-types'; import { Query } from 'react-apollo'; import gql from 'graphql-tag'; const QUERY = gql` query HeroFriends($episode: Episode!) { hero(episode: $episode) { name friends { name } } } `; const HeroAndFriends = ({ episode }) => ( <Query query={QUERY} variables={{ episode }}> {({ data, error, loading }) => { if (error) return '💩 Oops!'; if (loading) return 'Patience young grasshopper...'; return ( <React.Fragment> <h1>Hero: {data.hero.name}</h1> <h2>His/her friends:</h2> <ul> {data.hero.friends.map(friend => ( <li key={friend.name}>{friend.name}</li> ))} </ul> </React.Fragment> ); }} </Query> ); HeroAndFriends.propTypes = { episode: PropTypes.string }; HeroAndFriends.defaultProps = { episode: 'NEWHOPE' }; const App = () => <HeroAndFriends episode="EMPIRE" />; export default App;

And let’s breakdown the important things happening here:

React Apollo’s Query component takes a required query prop with a GraphQL query that has been parsed using graphql-tag’s gql . Query also takes a required children prop that should be a function. Here we also passed-in a variable prop to provide a variable value to our query.

component takes a required prop with a GraphQL query that has been parsed using graphql-tag’s . also takes a required prop that should be a function. Here we also passed-in a prop to provide a variable value to our query. Query can also take a number of optional props like pollInterval , fetchPolicy , errorPolicy and delay , among others.

can also take a number of optional props like , , and , among others. The function passed to the children prop receives an object with a handful of useful properties. Here we’re making use of data , error and loading , but other properties like networkStatus , refetch and fetchMore are also available.

, and , but other properties like , and are also available. The data property holds the data received back from the query, the error property holds an error object, if any, and the loading property will be true while the query is in-flight.