GraphQL and Apollo Client by Example: Part 1

GraphQL and Apollo Client can be intimidating to learn; but broken down they are straightforward and a pleasure to work with.

Through example, we will learn the basics of GraphQL and Apollo Client. We will start with managing local state and then move onto persisted (GraphQL server) state.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

— GraphQL — GraphQL

note: While I have used GraphQL and Apollo Client a couple of times, REST APIs with Redux has been my go-to strategy for state management in web application development. The ability to use Apollo Client to manage local state, however, is new to me (and might be a game-changer).

The final example for this series is available for download.

note: Since I wrote this, Apollo Client got some improvements; mostly an easier on-boarding experience with Apollo Boost. If you are looking to follow along writing your own code, recommend that you only read up until GraphQL and Apollo Client by Example: Part 6 where we start over with the simplified setup (and re-implement the work in the earlier parts).

Setup

Node.js and Apollo Client Developer Tools (and Chrome) are required if you wish to follow along on your own.

First we create a sample React project with:

npx create-react-app hello-apollo

In the project folder we install the various Apollo Client dependencies per the documentation.

yarn add apollo-boost react-apollo graphql-tag graphql

ApolloClient / ApolloProvider

To enable Apollo in our project we create an ApolloClient and use ApolloProvider to inject it into our component tree.

src/index.js

Observations:

• InMemoryCache is the defacto-standard mechanism to store data locally for ApolloClient
• withClientState enables the cache to hold local state; the example takes an object with four properties (one of which is the cache to use).

The resolvers property, imported from a separate module, will be used later to enable modifying (mutating) the local state.

src/graphql/resolvers.js

The defaults property, also imported from a separate module, defines the initial (default) local state. In this case an object with the property counter with value 0.

src/graphql/defaults.js

The typeDefs property, also imported from a separate module, defines the interface to the local state. In this case it defines a single query (reading data), counter, that returns an integer.

src/graphql/typeDefs

Observations:

• Unlike other GraphQL implementations, you do not need to define corresponding implementation (in resolvers) to query local state; because the cache already supplies it.

Now run the application.

yarn start

and use the Apollo tab in Chrome Developer Tools.

note: I randomly got errors using the Apollo tab (reloading the page or restarting the browser was the fix). One such behavior was an error on the Console about reading the property queryStore.

First, using the Documentation Explorer (Docs button in the upper right) we can see the counter query.

Second we can execute the counter query.

Observations:

• We supply the @client annotation to query the local state
• Above is shorthand for the more complete query syntax

query {
  counter @client
}

Next Steps

In the next article, GraphQL and Apollo Client by Example: Part 2, we will use the ApolloClient in a React component.

✉️ Subscribe to CodeBurst’s once-weekly Email Blast, 🐦 Follow CodeBurst on Twitter, view 🗺️ The 2018 Web Developer Roadmap, and 🕸️ Learn Full Stack Web Development.