Introduction

This is the official guide to using GraphQL in your React app with the Apollo JavaScript GraphQL client and the react-apollo integration package. For a step-by-step hands-on tutorial you can also check out the Learn Apollo website by Graphcool.

Get started now with the setup instructions.

See all of the available features with the API reference.

The Apollo community builds and maintains tools designed to make it easier to use GraphQL across a range of front-end and server technologies. Although this guide focuses on the integration with React, there is a similar guide for Angular 2, and the core apollo-client JavaScript package can be used anywhere JavaScript runs.

If you are looking to use Apollo with a native mobile client, there is an iOS Client in development and plans for an Android client too. On the other hand, the React integration documented here works with React Native on both platforms without changes.

You can learn more about the Apollo project at the project’s home page.

Apollo Client and React

The apollo-client Npm module is a JavaScript client for GraphQL. The goal of the package is to be:

  1. Incrementally adoptable, so that you can drop it into an existing JavaScript app and start using GraphQL for just part of your UI.
  2. Universally compatible, so that Apollo works with any build setup, any GraphQL server, and any GraphQL schema.
  3. Simple to get started with, you can just read this guide and get going.
  4. Inspectable and understandable, so that you can have great developer tools to understand exactly what is happening in your app.
  5. Built for interactive apps, so your users can make changes and see them reflected in the UI immediately.
  6. Community driven, many of the components of Apollo (including the react-apollo integration) are driven by the community and serve real-world use cases from the outset, and all projects are planned and developed in the open.

The Apollo client does more than simply run your queries against your GraphQL server. It analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run, fetching more results from the server. This means that your UI can be internally consistent and fully up-to-date with the state on the server with the minimum number of queries required.

The best way to use apollo-client in your React app is with react-apollo, a React-specific API that’s designed to take full advantage of Apollo’s features. The integration provides a natural “higher-order-component” API for queries and mutations, and will keep your rendered component tree up to date with the data in the cache seamlessly. The guide you’re currently reading describes react-apollo.

Compatibility

Apollo is designed to work with many of the tools used in a typical React app. In particular:

  • React Native: It’s supported out of the box!
  • Redux: Apollo client uses Redux internally, and you can integrate it into your existing store to use your favorite Redux tools such as the dev tools or persistence libraries. You can also use it alongside any other data management library, such as MobX, without issues.
  • Router-independent: You can use the library of your choice, such as React Router.
  • Any GraphQL server: It doesn’t matter if you use JavaScript, Ruby, Scala, or anything else to build your GraphQL server. Apollo works completely with standard GraphQL, and doesn’t have any requirements for your server or schema design.

Comparison with other GraphQL clients

If you are deciding whether to use react-apollo or some other GraphQL client, it’s worth considering the goals of the project, and how they compare. In particular:

  • Relay is a performant, opinionated, React-specific GraphQL client built by Facebook for their mobile applications. It focuses on enabling the co-location of queries and components, and is opinionated about the design of your GraphQL schema, especially in the case of pagination. Apollo has an analogous set of features to Relay, but is designed to be a general-purpose tool that can be used with any schema or any frontend architecture. Relay’s coupling to a specific kind of schema and architecture enables some benefits but with the loss of some flexibility, which also lets the Apollo community iterate more rapidly and quickly test experimental features.
  • Lokka is a simple GraphQL Javascript client with a basic query cache. Apollo is more complex, but includes a much more sophisticated cache and set of advanced features around updating and refetching data.

Learn More

To learn more about Apollo, and how to use it in React, visit:

Edit on GitHub