Setup and options

Installation

To get started with Apollo and React, install the apollo-client npm package, the react-apollo integration package, and the graphql-tag library for constructing query documents:

1
npm install react-apollo --save

Note: You don’t have to do anything special to get Apollo Client to work in React Native, just install and import it as usual.

To get started using Apollo with React, we need to create an ApolloClient and an ApolloProvider. ApolloClient serves as a central store of query result data which caches and distributes the results of our queries. ApolloProvider wires that client into our React component hierarchy.

Creating a client

To get started, create an ApolloClient instance and point it at your GraphQL server:

1
2
3
4
5
import { ApolloClient } from 'react-apollo';
// By default, this client will send queries to the
// `/graphql` endpoint on the same host
const client = new ApolloClient();

The client takes a variety of options, but in particular, if you want to change the URL of the GraphQL server, you can create a custom NetworkInterface:

1
2
3
4
5
import { ApolloClient, createNetworkInterface } from 'react-apollo';
const client = new ApolloClient({
networkInterface: createNetworkInterface({ uri: 'http://my-api.graphql.com' }),
});

ApolloClient has some other options which control the behavior of the client, and we’ll see examples of their use throughout this guide.

Creating a provider

To connect your client instance to your component tree, use an ApolloProvider component. You should be sure to place the ApolloProvider somewhere high in your view hierarchy, above any places where you need to access GraphQL data.

1
2
3
4
5
6
7
8
9
10
11
import { ApolloClient, ApolloProvider } from 'react-apollo';
// Create the client as outlined above
const client = new ApolloClient();
ReactDOM.render(
<ApolloProvider client={client}>
<MyRootComponent />
</ApolloProvider>,
domContainerNode
)

Connecting Data

The graphql() container is the recommended approach for fetching data or making mutations. It is a Higher Order Component for providing Apollo data to a component, or attaching mutations.

The basic usage of graphql() is as follows:

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
import React, { Component } from 'react';
import { gql, graphql } from 'react-apollo';
// MyComponent is a "presentational" or apollo-unaware component,
// It could be a simple React class:
class MyComponent extends Component {
render() {
return <div>...</div>;
}
}
// Or a stateless functional component:
const MyComponent = (props) => (
<div>...</div>
);
// Initialize GraphQL queries or mutations with the `gql` tag
const MyQuery = gql`query MyQuery { todos { text } }`;
const MyMutation = gql`mutation MyMutation { addTodo(text: "Test 123") { id } }`;
// We then can use `graphql` to pass the query results returned by MyQuery
// to MyComponent as a prop (and update them as the results change)
const MyComponentWithData = graphql(MyQuery)(MyComponent);
// Or, we can bind the execution of MyMutation to a prop
const MyComponentWithMutation = graphql(MyMutation)(MyComponent);

If you are using ES2016 decorators, you may prefer the decorator syntax:

1
2
3
4
5
6
7
8
9
10
import React, { Component } from 'react';
import { graphql } from 'react-apollo';
@graphql(MyQuery)
@graphql(MyMutation)
class MyComponent extends Component {
render() {
return <div>...</div>;
}
}

In this guide, we won’t use the decorator syntax to make the code more familiar, but you can always use it if you prefer.

To see the complete API for the graphql() function be sure to checkout the API reference.

Edit on GitHub