If you are a front end developer who is new to the world of GraphQL and you're thinking about getting started with it, this article is for you.

In this article, we will explore GraphQL basics and kick start our journey with it by building a simple project.

What is GraphQL?

GraphQL is a query language that lets apps fetch data from the API's. But what it does differently is that is allows clients to specify how to structure the data when it is returned by the server. This means that the client only asks for the data it needs and even specifies the format in which it needs the data.

But what problem does it actually solve?

It solves the problem of under fetching and over fetching. Ok but what's that? Well, let me tell you.

Let's say you only need to display a userName, userImage, and Name in your profile page on your website or app. But when you request the data you are getting lots of other information about the user which you don't need.

This is called over fetching – you are fetching a lot of data, even the data you don't need. On the other hand, under fetching is when we get less data than you need. So neither one is great.

under Fetching example

You might think ok, that's not a problem at all. Well, it's not a big problem in small scale applications. But what about in large scale applications that have millions of users? In those cases, over fetching and under fetching waste a lot of resources, which is where GraphQL comes in.

How to Get Started With GraphQL

Here we'll cover some key concepts you need to know before getting started with graphQL

GraphQL PlayGround

GraphQL playground is an interactive, Graphical IDE for GraphQL where you can visually explore the server. In it you can test various GraphQL queries and see their results in front of your eyes.

Here is a link to GraphQL playground you can check out.

GraphQL playground

If you click on the play button it will run the query.

How do you request, write, or post data in GraphQL?

You request data through a query in GraphQL. And to write or post data, you use mutations.

Whenever we perform a GraphQL operation, we specify whether it is a mutation or a query. Then we name that operation, and this is the basic way of performing a GraphQL query.

GraphQLOperatoinType Name {
 ....
 ........
 .....
 ...
}

To make a simple query, the syntax would be:

query getData {
...
}

Similarly, to add a mutation we would write mutation in place of query.

Now since we know the basics, let's get our hands dirty. We will be using the Anilist API to get a list of anime shows.

Apollo studio

How to Use Apollo Studio

You've gotten a small taste of GraphQL playground, but there's something even more awesome called Apollo Studio. It makes life easier as a front end developer. In it, you just need select the fields you want and it writes a query for you.

From the left hand side select the fields you want in your Query, and that's it. GraphQL will automatically create a query for you. Now you've made the query, but how do you use it in your application?

Well let's get started building a simple Anime App with it.

We'll use React in this project, but you can choose any framework or library you'd like.

Firstly, create a new project in React:

npx create-react-app graphql-example

Now once the project is created go inside the project directory and install the Apollo client.

npm install graphql @apollo/client

Once it's done, go the src/index.js and import ApolloClient, InMemoryCache, and ApolloProvider:

import {ApolloClient, InMemoryCache, ApolloProvider} from '@apollo/client';

Apollo Client is a class which represents the Apollo client itself, and we use it to create a new client instance.

Here we need to provide a couple of things to it. One is the URI where we specify the URL of our GraphQL server. Also every instance of our Apollo client needs a cache so it can reduce the network requests and can make our app much faster.

This is what our new client look like:

const client = new ApolloClient({
  uri : 'https://graphql.anilist.co/',
  cache: new InMemoryCache(),
})

Now we need to make this client available throughout our component tree so we wrap our app's top level component in ApolloProvider.

Now we are done with the initial setup, so it's time to make a query and ask our API for the data – but how do we do that?

We can do so using the useQuery hook. But before that we need to define a query, which we can do using the GQL (we need to wrap our query inside it). So now, import these two from the Apollo client:

import {useQuery, gql} from '@apollo/client';

After importing them, we'll wrap our query inside GQL:

 const AnimeList = gql`
 query Query {
  Page {
    media {
      siteUrl
      title {
        english
        native
      }
      description
      coverImage {
        medium
      }
      bannerImage
      volumes
      episodes
    }
  }
}
}



`;

At this point you must be wondering if the query part is done, how do we get data from it now?

That's where the useQuery hook comes handy. It returns loading, error, and data properties we can use.

  const {loading, error, data} = useQuery(AnimeList);

For now we can just display the data to check whether our app works or not:

if(loading) return(<> Loading</>);
  if(error) return(<>{JSON.stringify(error)}</>)
  return (
   <>
   {JSON.stringify(data)}
   </>);

Well it works for now – time to style it.

Maybe we can use object chaining to implement that nicely:

 <div className="container"> 
     <h1> 🐈 Anime List </h1>
     <hr width="80%" />
   {data?.Page?.media.map(anime => (
     <>
   <div className="card" >
      <img    src={anime.coverImage.medium}/>
      <div> 
         <h1>{anime.title.english} </h1>
           <div className="episodes" >Episodes  <b>{anime.episodes} </b></div>
          <div  dangerouslySetInnerHTML={{__html: anime.description}} ></div> 
      </div> 
  </div>
  <hr width="75%"/>
 </>
   ))}
   <div className="buttonContainer">
    { page != 1 && <button> Previous Page</button> } 
     <div className="pageText"> {page}</div>
     <button onClick={NextPage}>  Next Page </button> 
   </div>
   </div>);

minimistic styled app

You can check out this GitHub repo for the CSS file.

Now we are able to get a list of anime films from the API. So what do we need to get them from the next page of the app?

We need to pass a variable that has a page name into the query. That's where variables in GraphQL come into the picture.

First, go to Apollo Studio and click on the arguments on the left hand side (first go to root > query >page and you'll see it):

Click on page and it'll add an argument to your query.

Also notice that in the variable page in the variables section, you can change its value and play around a little bit with it. But the data will only change according to the page.

Now we need to pass this variable into the query – and then we'll be able to display next page's anime in our app.

For that we'll be using the useState hook to keep a track of our current page's value. We also need to make a function to increment and decrement that as well.

  const [page, setPage] = useState(1);
  //this is how we would be passing the page in the query.
  const {loading, error, data} = useQuery(AnimeList , {  variables: { "page" : page } });

const NextPage = () => {
    setPage(page+1);
  }
  const PreviousPage = () => {
    setPage(page - 1);
  }

   <div className="buttonContainer">
    { page != 1 && <button onClick={PreviousPage}> Previous Page</button> } 
     <div className="pageText"> {page}</div>
     <button onClick={NextPage}>  Next Page </button> 
   </div>

And now we're done building our simple app with GraphQL. If you want to check out the codebase, here is the link.

Wrapping Up

In this article, we have covered some of the basic concepts to help you get started using GraphQL. Thank you for reading, and happy coding.

While there are a couple of popular libraries which are made to interact with GraphQL APIs from a React application, there are many different ways to fetch data with GraphQL.

I've included code samples that show you how to fetch or "query" data in the shortest code possible and how to get up and running with each of these different methods of connecting React with GraphQL.

Getting Started

In these examples, we'll be using the SpaceX GraphQL API to fetch and display the past 10 missions that SpaceX has made.

Feel free to use the code below if you are attempting to connect your React app with a GraphQL API. In these examples, we're going to go from the most advanced GraphQL client library for React to the simplest approach to querying a GraphQL endpoint.

1. Apollo Client

The most popular and comprehensive GraphQL library is Apollo Client.

Not only can you use it to fetch remote data with GraphQL, which we're doing here, but it allows us to manage data locally, both through an internal cache as well as an entire state management API.

To get started with Apollo Client, you need to install both the main Apollo Client dependency, as well as GraphQL:

npm install @apollo/client graphql

The idea behind the Apollo Client is that it will be used across your entire application. To do this, you'll use a special Apollo Provider component to pass a created Apollo client down your entire component tree.

When you create your Apollo Client, you need to specify a uri value, namely a GraphQL endpoint. Additionally, you need to specify a cache.

Apollo Client comes with its own in memory cache, which is used to cache or locally store and manage your queries and their related data:

import React from "react";
import ReactDOM from "react-dom";
import { ApolloProvider, ApolloClient, InMemoryCache } from "@apollo/client";

import App from "./App";

const client = new ApolloClient({
  uri: "https://api.spacex.land/graphql/",
  cache: new InMemoryCache()
});

const rootElement = document.getElementById("root");
ReactDOM.render(
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>,
  rootElement
);

Once you've set up the Provider and client within your App component, you can use all of the different React hooks that Apollo Client gives you for all the different GraphQL operations. These include queries, mutations, and subscriptions. You can even use the created Apollo Client directly using a custom hook called useApolloClient.

Since you're just querying data here, you will use the useQuery hook.

You will include a GraphQL query as its first argument to write your query. You'll use the function gql, which does a number of things, such as giving you editor syntax highlighting and the auto formatting functionality if you use the tool Prettier for your project.

Once you execute this query, you get back the values data, loading, and error:

import React from "react";
import { useQuery, gql } from "@apollo/client";

const FILMS_QUERY = gql`
  {
    launchesPast(limit: 10) {
      id
      mission_name
    }
  }
`;

export default function App() {
  const { data, loading, error } = useQuery(FILMS_QUERY);

  if (loading) return "Loading...";
  if (error) return <pre>{error.message}</pre>

  return (
    <div>
      <h1>SpaceX Launches</h1>
      <ul>
        {data.launchesPast.map((launch) => (
          <li key={launch.id}>{launch.mission_name}</li>
        ))}
      </ul>
    </div>
  );
}

Before you display your data, your missions, you want to handle the loading state. When you are in a loading state, you are fetching the query from a remote endpoint.

You also want to handle any errors that occur. You can simulate an error by making a syntax error in your query, such as querying for a field that doesn't exist. To handle that error, you can conveniently return and display a message from error.message.

2. Urql

Another fully-featured library that connects React apps with GraphQL APIs is urql.

It attempts to give you many of the features and syntax Apollo has while being a little bit smaller in size and requiring less setup code. It gives you caching capabilities if you choose, but it does not include an integrated state management library like Apollo does.

To use urql as your GraphQL client library, you'll need to install the packages urql and GraphQL.

npm install urql graphql

Just like Apollo, you'll want to use the dedicated Provider component, and create a client with your GraphQL endpoint. Note that you do not need to specify a cache out of the box.

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import { createClient, Provider } from 'urql';

const client = createClient({
  url: 'https://api.spacex.land/graphql/',
});

const rootElement = document.getElementById("root");
ReactDOM.render(
  <Provider value={client}>
    <App />
  </Provider>,
  rootElement
);

Very similar to Apollo, urql gives you custom hooks that handle all the standard GraphQL operations, and therefore have similar names.

Again, you can use the useQuery hook from the urql package. Although instead of needing the function gql, you can drop it and just use a template literal to write your query.

When calling useQuery, you get back an array which you can destructure as an array instead of as an object. The first element in this array is an object, called result, which gives you a number of properties that you can destructure: data, fetching, and error.

import React from "react";
import { useQuery } from 'urql';

const FILMS_QUERY = `
  {
    launchesPast(limit: 10) {
      id
      mission_name
    }
  }
`;

export default function App() {
  const [result] = useQuery({
    query: FILMS_QUERY,
  });

  const { data, fetching, error } = result;

  if (fetching) return "Loading...";
  if (error) return <pre>{error.message}</pre>

  return (
    <div>
      <h1>SpaceX Launches</h1>
      <ul>
        {data.launchesPast.map((launch) => (
          <li key={launch.id}>{launch.mission_name}</li>
        ))}
      </ul>
    </div>
  );
}

In an identical fashion to displaying the data that you fetch with Apollo, you can handle both your error and loading states while you're fetching your remote data.

3. React Query + GraphQL Request

It's important to note at this point that you don't need a sophisticated, heavyweight GraphQL client library like urql or Apollo to interact with your GraphQL API, as we will see later.

Libraries like Apollo and urql were created not only to help you perform all the standard GraphQL operations, but to better manage the server state in your React client through a number of additional tools. All this along with the fact that they come with custom hooks that make managing repetitive tasks like handling loading, error, and other related states simple.

With that in mind, let's take a look at how you can use a very pared-down GraphQL library for your data fetching and combine that with a better means of managing and caching that server state that you're bringing into your application. You can fetch data very simply with the help of the package graphql-request.

GraphQL Request is a library that doesn't require you to set up a client or a Provider component. It is essentially a function that just accepts an endpoint and a query. Very similar to an HTTP client, you just have to pass in those two values and you get back your data.

Now if you want to manage that state across your app, you can use a great library normally used for interacting with Rest APIs – but it's equally helpful for GraphQL APIs – and that is React Query. It gives you some very similarly named React Hooks, useQuery and useMutation, that perform identical tasks to what the Apollo and urql hooks perform.

React Query also gives you a bunch of tools for managing state, along with an integrated Dev Tools component that allows you to see what's being stored in React Query's built-in cache.

By pairing your very basic GraphQL client, GraphQL request, with React Query you get all the power of a library like urql or Apollo.

To get started with this pairing, you just need to install React Query and GraphQL Request:

npm install react-query graphql-request

You use React Query's Provider component and create a query client where you can set some default data fetching settings if you like. Then within your app component itself, or any child components of App, you can use the useQuery hook.

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import { QueryClient, QueryClientProvider } from "react-query";

const client = new QueryClient();

const rootElement = document.getElementById("root");
ReactDOM.render(
  <QueryClientProvider client={client}>
    <App />
  </QueryClientProvider>,
  rootElement
);

To store the result of your operation in the React Query cache, you just need to give it a key value as the first argument to serve as an identifier. This allows you to very easily reference and pull data from the cache, as well as to refetch or invalidate a given query to fetch updated data.

Since you're fetching launch data, let's call this query "launches".

Once again, this hook will return the result of making that request. For the second argument to useQuery, you need to specify how to fetch that data and React Query will take care of resolving the promise that GraphQL request returns.

import React from "react";
import { request, gql } from "graphql-request";
import { useQuery } from "react-query";

const endpoint = "https://api.spacex.land/graphql/";
const FILMS_QUERY = gql`
  {
    launchesPast(limit: 10) {
      id
      mission_name
    }
  }
`;

export default function App() {
  const { data, isLoading, error } = useQuery("launches", () => {
    return request(endpoint, FILMS_QUERY);
  });

  if (isLoading) return "Loading...";
  if (error) return <pre>{error.message}</pre>;

  return (
    <div>
      <h1>SpaceX Launches</h1>
      <ul>
        {data.launchesPast.map((launch) => (
          <li key={launch.id}>{launch.mission_name}</li>
        ))}
      </ul>
    </div>
  );
}

Similar to Apollo, you get back an object that you can destructure to get the values for the data, as well as whether or not you're in the loading state, and the error state.

4. React Query + Axios

You can use even simpler HTTP client libraries that have no relationship to GraphQL to fetch your data.

In this case, you can use the popular library axios. Once again you can pair it with React Query to get all the special hooks and state management.

npm install react-query axios

Using an HTTP client like Axios to perform a query from a GraphQL API requires performing a POST request to your API endpoint. For the data that you send along in the request, you will provide an object with a property called query, which will be set to your films query.

With axios, you're going to need to include a little bit more information about how to resolve this promise and get back your data. You need to tell React Query where the data is so it can be put on the data property that useQuery returns.

In particular, you get the data back on the data property of response.data:

import React from "react";
import axios from "axios";
import { useQuery } from "react-query";

const endpoint = "https://api.spacex.land/graphql/";
const FILMS_QUERY = `
  {
    launchesPast(limit: 10) {
      id
      mission_name
    }
  }
`;

export default function App() {
  const { data, isLoading, error } = useQuery("launches", () => {
    return axios({
      url: endpoint,
      method: "POST",
      data: {
        query: FILMS_QUERY
      }
    }).then(response => response.data.data);
  });

  if (isLoading) return "Loading...";
  if (error) return <pre>{error.message}</pre>;

  return (
    <div>
      <h1>SpaceX Launches</h1>
      <ul>
        {data.launchesPast.map((launch) => (
          <li key={launch.id}>{launch.mission_name}</li>
        ))}
      </ul>
    </div>
  );
}

5. React Query + Fetch API

The easiest way of all these different approaches to fetch data is to just use React query plus the fetch API.

Since the fetch API is included in all modern browsers, you do not need to install a third-party library – you only need to install react-query within your application.

npm install react-query

Once you have the React Query client provided to the entire app, you can just swap out your axios code with fetch.

What's a little bit different is that you need to specify a header that includes the content type of the data that you want back from your request. In this case, it is JSON data.

You also need to stringify the object that you're sending as your payload with a query property that is set to your films query:

import React from "react";
import axios from "axios";
import { useQuery } from "react-query";

const endpoint = "https://api.spacex.land/graphql/";
const FILMS_QUERY = `
  {
    launchesPast(limit: 10) {
      id
      mission_name
    }
  }
`;

export default function App() {
  const { data, isLoading, error } = useQuery("launches", () => {
    return fetch(endpoint, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query: FILMS_QUERY })
    })
      .then((response) => {
        if (response.status >= 400) {
          throw new Error("Error fetching data");
        } else {
          return response.json();
        }
      })
      .then((data) => data.data);
  });

  if (isLoading) return "Loading...";
  if (error) return <pre>{error.message}</pre>;

  return (
    <div>
      <h1>SpaceX Launches</h1>
      <ul>
        {data.launchesPast.map((launch) => (
          <li key={launch.id}>{launch.mission_name}</li>
        ))}
      </ul>
    </div>
  );
}

One benefit of using axios over fetch is that it automatically handles errors for you. With fetch, as you can see in the code above, you need to check for a certain status code, in particular a status code above 400.

This means that your request resolves to an error. If that's the case, you need to manually throw an error, which will be caught by your useQuery hook. Otherwise, if it's a 200 or 300 range response, meaning the request was successful, simply return the JSON data and display it.

Conclusion

This article was dedicated to showing you a number of different approaches to effectively fetching data from a GraphQL API with React.

From these options, hopefully you can evaluate which is most appropriate for you and your applications. And now you have some helpful code that will enable you to start using these tools and libraries much faster.

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

I've put together a comprehensive cheatsheet that goes through all of the core concepts in the Apollo library, showing you how to use it with React from front to back.

Want Your Own Copy?

You can grab the PDF cheatsheet right here (it takes 5 seconds).

Here are some quick wins from grabbing the downloadable version:

• ✓ Quick reference to review however and whenever
• ✓ Tons of useful code snippets based off of real-world projects
• ✓ Read this guide offline, wherever you like. On the train, at your desk, standing in line — anywhere.

Prefer Video Lessons?

A great deal of this cheatsheet is based off of the app built in the React + GraphQL 2020 Crash Course.

If you want some more hands-on video lessons, plus see how to build apps with React, GraphQL and Apollo, you can watch the course right here.

Note: This cheatsheet does assume familiarity with React and GraphQL. If you need a quick refresher on GraphQL and how to write it, a great resource is the official GraphQL website.

Table of Contents

Getting Started

• What is Apollo and why do we need it?
• Apollo Client setup
• Creating a new Apollo Client
• Providing the client to React components
• Using the client directly
• Writing GraphQL in .js files with gql

Core Apollo React Hooks

• useQuery Hook
• useLazyQuery Hook
• useMutation Hook
• useSubscription Hook

Essential Recipes

• Manually setting the fetch policy
• Updating the cache upon a mutation
• Refetching queries with useQuery
• Refetching queries with useMutation
• Accessing the client with useApolloClient

What is Apollo and why do we need it?

Apollo is a library that brings together two incredibly useful technologies used to build web and mobile apps: React and GraphQL.

React was made for creating great user experiences with JavaScript. GraphQL is a very straightforward and declarative new language to more easily and efficiently fetch and change data, whether it is from a database or even from static files.

Apollo is the glue that binds these two tools together. Plus it makes working with React and GraphQL a lot easier by giving us a lot of custom React hooks and features that enable us to both write GraphQL operations and execute them with JavaScript code.

We'll cover these features in-depth throughout the course of this guide.

Apollo Client basic setup

If you are starting a project with a React template like Create React App, you will need to install the following as your base dependencies to get up and running with Apollo Client:

// with npm:
npm i @apollo/react-hooks apollo-boost graphql

// with yarn:
yarn add @apollo/react-hooks apollo-boost graphql

@apollo/react-hooks gives us React hooks that make performing our operations and working with Apollo client better

apollo-boost helps us set up the client along with parse our GraphQL operations

graphql also takes care of parsing the GraphQL operations (along with gql)

Apollo Client + subscriptions setup

To use all manner of GraphQL operations (queries, mutations, and subscriptions), we need to install more specific dependencies as compared to just apollo-boost:

// with npm:
npm i @apollo/react-hooks apollo-client graphql graphql-tag apollo-cache-inmemory apollo-link-ws

// with yarn:
yarn add @apollo/react-hooks apollo-client graphql graphql-tag apollo-cache-inmemory apollo-link-ws

apollo-client gives us the client directly, instead of from apollo-boost

graphql-tag is integrated into apollo-boost, but not included in apollo-client

apollo-cache-inmemory is needed to setup our own cache (which apollo-boost, in comparison, does automatically)

apollo-link-ws is needed for communicating over websockets, which subscriptions require

Creating a new Apollo Client (basic setup)

The most straightforward setup for creating an Apollo client is by instantiating a new client and providing just the uri property, which will be your GraphQL endpoint:

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
  uri: "https://your-graphql-endpoint.com/api/graphql",
});

apollo-boost was developed in order to make doing things like creating an Apollo Client as easy as possible. What it lacks for the time being, however, is support for GraphQL subscriptions over a websocket connection.

By default, it performs the operations over an http connection (as you can see through our provided uri above).

In short, use apollo-boost to create your client if you only need to execute queries and mutations in your app.

It setups an in-memory cache by default, which is helpful for storing our app data locally. We can read from and write to our cache to prevent having to execute our queries after our data is updated. We'll cover how to do that a bit later.

Creating a new Apollo Client (+ subscriptions setup)

Subscriptions are useful for more easily displaying the result of data changes (through mutations) in our app.

Generally speaking, we use subscriptions as an improved kind of query. Subscriptions use a websocket connection to 'subscribe' to updates and data, enabling new or updated data to be immediately displayed to our users without having to reexecute queries or update the cache.

import ApolloClient from "apollo-client";
import { WebSocketLink } from "apollo-link-ws";
import { InMemoryCache } from "apollo-cache-inmemory";

const client = new ApolloClient({
  link: new WebSocketLink({
    uri: "wss://your-graphql-endpoint.com/v1/graphql",
    options: {
      reconnect: true,
      connectionParams: {
        headers: {
          Authorization: "Bearer yourauthtoken",
        },
      },
    },
  }),
  cache: new InMemoryCache(),
});

Providing the client to React components

After creating a new client, passing it to all components is essential in order to be able to use it within our components to perform all of the available GraphQL operations.

The client is provided to the entire component tree using React Context, but instead of creating our own context, we import a special context provider from @apollo/react-hooks called ApolloProvider . We can see how it differs from the regular React Context due to it having a special prop, client, specifically made to accept the created client.

Note that all of this setup should be done in your index.js or App.js file (wherever your Routes declared) so that the Provider can be wrapped around all of your components.

import { ApolloProvider } from "@apollo/react-hooks";

const rootElement = document.getElementById("root");
ReactDOM.render(
  <React.StrictMode>
    <ApolloProvider client={client}>
      <BrowserRouter>
        <Switch>
          <Route exact path="/" component={App} />
          <Route exact path="/new" component={NewPost} />
          <Route exact path="/edit/:id" component={EditPost} />
        </Switch>
      </BrowserRouter>
    </ApolloProvider>
  </React.StrictMode>,
  rootElement
);

Using the client directly

The Apollo client is most important part of the library due to the fact that it is responsible for executing all of the GraphQL operations that we want to perform with React.

We can use the created client directly to perform any operation we like. It has methods corresponding to queries (client.query()), mutations (client.mutate()), and subscriptions (client.subscribe()).

Each method accepts an object and it's own corresponding properties:

// executing queries
client
  .query({
    query: GET_POSTS,
    variables: { limit: 5 },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

// executing mutations
client
  .mutate({
    mutation: CREATE_POST,
    variables: { title: "Hello", body: "World" },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

// executing subscriptions
client
  .subscribe({
    subscription: GET_POST,
    variables: { id: "8883346c-6dc3-4753-95da-0cc0df750721" },
  })
  .then((response) => console.log(response.data))
  .catch((err) => console.error(err));

Using the client directly can be a bit tricky, however, since in making a request, it returns a promise. To resolve each promise, we either need .then() and .catch() callbacks as above or to await each promise within a function declared with the async keyword.

Writing GraphQL operations in .js files (gql)

Notice above that I didn't specify the contents of the variables GET_POSTS, CREATE_POST, and GET_POST.

They are the operations written in the GraphQL syntax which specify how to perform the query, mutation, and subscription respectively. They are what we would write in any GraphiQL console to get and change data.

The issue here, however, is that we can't write and execute GraphQL instructions in JavaScript (.js) files, like our React code has to live in.

To parse the GraphQL operations, we use a special function called a tagged template literal to allow us to express them as JavaScript strings. This function is named gql.

// if using apollo-boost
import { gql } from "apollo-boost";
// else, you can use a dedicated package graphql-tag
import gql from "graphql-tag";

// query
const GET_POSTS = gql`
  query GetPosts($limit: Int) {
    posts(limit: $limit) {
      id
      body
      title
      createdAt
    }
  }
`;

// mutation
const CREATE_POST = gql`
  mutation CreatePost($title: String!, $body: String!) {
    insert_posts(objects: { title: $title, body: $body }) {
      affected_rows
    }
  }
`;

// subscription
const GET_POST = gql`
  subscription GetPost($id: uuid!) {
    posts(where: { id: { _eq: $id } }) {
      id
      body
      title
      createdAt
    }
  }
`;

useQuery Hook

The useQuery hook is arguably the most convenient way of performing a GraphQL query, considering that it doesn't return a promise that needs to be resolved.

It is called at the top of any function component (as all hooks should be) and receives as a first required argument—a query parsed with gql.

It is best used when you have queries that should be executed immediately, when a component is rendered, such as a list of data which the user would want to see immediately when the page loads.

useQuery returns an object from which we can easily destructure the values that we need. Upon executing a query, there are three primary values will need to use within every component in which we fetch data. They are loading, error, and data.

const GET_POSTS = gql`
  query GetPosts($limit: Int) {
    posts(limit: $limit) {
      id
      body
      title
      createdAt
    }
  }
`;

function App() {
  const { loading, error, data } = useQuery(GET_POSTS, {
    variables: { limit: 5 },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  return data.posts.map((post) => <Post key={post.id} post={post} />);
}

Before we can display the data that we're fetching, we need to handle when we're loading (when loading is set to true) and we are attempting to fetch the data.

At that point, we display a div with the text 'Loading' or a loading spinner. We also need to handle the possibility that there is an error in fetching our query, such as if there's a network error or if we made a mistake in writing our query (syntax error).

Once we're done loading and there's no error, we can use our data in our component, usually to display to our users (as we are in the example above).

There are other values which we can destructure from the object that useQuery returns, but you'll need loading, error, and data in virtually every component where you execute useQuery. You can see a full list of all of the data we can get back from useQuery here.

useLazyQuery Hook

The useLazyQuery hook provides another way to perform a query, which is intended to be executed at some time after the component is rendered or in response to a given data change.

useLazyQuery is very useful for things that happen at any unknown point of time, such as in response to a user's search operation.

function Search() {
  const [query, setQuery] = React.useState("");
  const [searchPosts, { data }] = useLazyQuery(SEARCH_POSTS, {
    variables: { query: `%${query}%` },
  });
  const [results, setResults] = React.useState([]);

  React.useEffect(() => {
    if (!query) return;
    // function for executing query doesn't return a promise
    searchPosts();
    if (data) {
      setResults(data.posts);
    }
  }, [query, data, searchPosts]);

  if (called && loading) return <div>Loading...</div>;

  return results.map((result) => (
    <SearchResult key={result.id} result={result} />
  ));
}

useLazyQuery differs from useQuery, first of all, in what's returned from the hook. It returns an array which we can destructure, instead of an object.

Since we want to perform this query sometime after the component is mounted, the first element that we can destructure is a function which you can call to perform that query when you choose. This query function is named searchPosts in the example above.

The second destructured value in the array is an object, which we can use object destructuring on and from which we can get all of the same properties as we did from useQuery, such as loading, error, and data.

We also get an important property named called, which tells us if we've actually called this function to perform our query. In that case, if called is true and loading is true, we want to return "Loading..." instead of our actual data, because are waiting for the data to be returned. This is how useLazyQuery handles fetching data in a synchronous way without any promises.

Note that we again pass any required variables for the query operation as a property, variables, to the second argument. However, if we need, we can pass those variables on an object provided to the query function itself.

useMutation Hook

Now that we know how to execute lazy queries, we know exactly how to work with the useMutation hook.

Like the useLazyQuery hook, it returns an array which we can destructure into its two elements. In the first element, we get back a function, which in this case, we can call it to perform our mutation operation. For next element, we can again destructure an object which returns to us loading, error and data.

import { useMutation } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

const CREATE_POST = gql`
  mutation CreatePost($title: String!, $body: String!) {
    insert_posts(objects: { body: $body, title: $title }) {
      affected_rows
    }
  }
`;

function NewPost() {
  const [title, setTitle] = React.useState("");
  const [body, setBody] = React.useState("");
  const [createPost, { loading, error }] = useMutation(CREATE_POST);

  function handleCreatePost(event) {
    event.preventDefault();
    // the mutate function also doesn't return a promise
    createPost({ variables: { title, body } });
  }

  return (
    <div>
      <h1>New Post</h2>
      <form onSubmit={handleCreatePost}>
        <input onChange={(event) => setTitle(event.target.value)} />
        <textarea onChange={(event) => setBody(event.target.value)} />
        <button disabled={loading} type="submit">
          Submit
        </button>
        {error && <p>{error.message}</p>}
      </form>
    </div>
  );
}

Unlike with queries, however, we don't use loading or error in order to conditionally render something. We generally use loading in such situations as when we're submitting a form to prevent it being submitted multiple times, to avoid executing the same mutation needlessly (as you can see in the example above).

We use error to display what goes wrong with our mutation to our users. If for example, some required values to our mutation are not provided, we can easily use that error data to conditionally render an error message within the page so the user can hopefully fix what's going wrong.

As compared to passing variables to the second argument of useMutation, we can access a couple of useful callbacks when certain things take place, such as when the mutation is completed and when there is an error. These callbacks are named onCompleted and onError.

The onCompleted callback gives us access to the returned mutation data and it's very helpful to do something when the mutation is done, such as going to a different page. The onError callback gives us the returned error when there is a problem with the mutation and gives us other patterns for handling our errors.

const [createPost, { loading, error }] = useMutation(CREATE_POST, {
  onCompleted: (data) => console.log("Data from mutation", data),
  onError: (error) => console.error("Error creating a post", error),
});

useSubscription Hook

The useSubscription hook works just like the useQuery hook.

useSubscription returns an object that we can destructure, that includes the same properties, loading, data, and error.

It executes our subscription immediately when the component is rendered. This means we need to handle loading and error states, and only afterwards display/use our data.

import { useSubscription } from "@apollo/react-hooks";
import gql from "graphql-tag";

const GET_POST = gql`
  subscription GetPost($id: uuid!) {
    posts(where: { id: { _eq: $id } }) {
      id
      body
      title
      createdAt
    }
  }
`;

// where id comes from route params -> /post/:id
function PostPage({ id }) {
  const { loading, error, data } = useSubscription(GET_POST, {
    variables: { id },
    // shouldResubscribe: true (default: false)
    // onSubscriptionData: data => console.log('new data', data)
    // fetchPolicy: 'network-only' (default: 'cache-first')
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  const post = data.posts[0];

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </div>
  );
}

Just like useQuery, useLazyQuery and useMutation, useSubscription accepts variables as a property provided on the second argument.

It also accepts, however, some useful properties such as shouldResubscribe. This is a boolean value, which will allow our subscription to automatically resubscribe, when our props change. This is useful for when we're passing variables to our you subscription hub props that we know will change.

Additionally, we have a callback function called onSubscriptionData, which enables us to call a function whenever the subscription hook receives new data. Finally, we can set the fetchPolicy, which defaults to 'cache-first'.

Manually Setting the Fetch Policy

What can be very useful about Apollo is that it comes with its own cache, which it uses to manage the data that we query from our GraphQL endpoint.

Sometimes, however, we find that due to this cache, things aren't updated in the UI in the way that we want.

In many cases we don't, as in the example below, where we are editing a post on the edit page, and then after editing our post, we navigate to the home page to see it in a list of all posts, but we see the old data instead:

// route: /edit/:postId
function EditPost({ id }) {
  const { loading, data } = useQuery(GET_POST, { variables: { id } });
  const [title, setTitle] = React.useState(loading ? data?.posts[0].title : "");
  const [body, setBody] = React.useState(loading ? data?.posts[0].body : "");
  const [updatePost] = useMutation(UPDATE_POST, {
    // after updating the post, we go to the home page
    onCompleted: () => history.push("/"),
  });

  function handleUpdatePost(event) {
    event.preventDefault();
    updatePost({ variables: { title, body, id } });
  }

  return (
    <form onSubmit={handleUpdatePost}>
      <input
        onChange={(event) => setTitle(event.target.value)}
        defaultValue={title}
      />
      <input
        onChange={(event) => setBody(event.target.value)}
        defaultValue={body}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

// route: / (homepage)
function App() {
  const { loading, error, data } = useQuery(GET_POSTS, {
    variables: { limit: 5 },
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error!</div>;

  // updated post not displayed, still see old data
  return data.posts.map((post) => <Post key={post.id} post={post} />);
}

This not only due to the Apollo cache, but also the instructions for what data the query should fetch. We can changed how the query is fetched by using the fetchPolicy property.

By default, the fetchPolicy is set to 'cache-first'. It's going to try to look at the cache to get our data instead of getting it from the network.

An easy way to fix this problem of not seeing new data is to change the fetch policy. However, this approach is not ideal from a performance standpoint, because it requires making an additional request (using the cache directly does not, because it is local data).

There are many different options for the fetch policy listed below:

{
  fetchPolicy: "cache-first"; // default
  /* 
    cache-and-network
    cache-first
    cache-only
    network-only
    no-cache
    standby
  */
}

I won't go into what each policy does exactly, but to solve our immediate problem, if you always want a query to get the latest data by requesting it from the network, we set fetchPolicy to 'network-first'.

const { loading, error, data } = useQuery(GET_POSTS, {
  variables: { limit: 5 },
  fetchPolicy: "network-first"
});

Updating the cache upon a mutation

Instead of bypassing the cache by changing the fetch policy of useQuery, let's attempt to fix this problem by manually updating the cache.

When performing a mutation with useMutation. We have access to another callback, known as update.

update gives us direct access to the cache as well as the data that is returned from a successful mutation. This enables us to read a given query from the cache, take that new data and write the new data to the query, which will then update what the user sees.

Working with the cache manually is a tricky process that a lot of people tend to avoid, but it's very helpful because it saves some time and resources by not having to perform the same request multiple times to update the cache manually.

function EditPost({ id }) {
  const [updatePost] = useMutation(UPDATE_POST, {
    update: (cache, data) => {
      const { posts } = cache.readQuery(GET_POSTS);
      const newPost = data.update_posts.returning;
      const updatedPosts = posts.map((post) =>
        post.id === id ? newPost : post
      );
      cache.writeQuery({ query: GET_POSTS, data: { posts: updatedPosts } });
    },
    onCompleted: () => history.push("/"),
  });

  // ...
}

We first want to read the query and get the previous data from it. Then we need to take the new data. In this case, to find the post with a given id and replace it with newPost data, otherwise have it be the previous data, and then write that data back to the same query, making sure that it has the same data structure as before.

After all this, whenever we edit a post and are navigated back to the home page, we should see that new post data.

Refetching queries with useQuery

Let's say we display a list of posts using a GET_POSTS query and are deleting one of them with a DELETE_POST mutation.

When a user deletes a post, what do we want to happen?

Naturally, we want it to be removed from the list, both the data and what is displayed to the users. When a mutation is performed, however, the query doesn't know that the data is changed.

There are a few ways of updating what we see, but one approach is to reexecute the query.

We can do so by grabbing the refetch function which we can destructure from the object returned by the useQuery hook and pass it down to the mutation to be executed when it is completed, using the onCompleted callback function:

function Posts() {
  const { loading, data, refetch } = useQuery(GET_POSTS);

  if (loading) return <div>Loading...</div>;

  return data.posts.map((post) => (
    <Post key={post.id} post={post} refetch={refetch} />
  ));
}

function Post({ post, refetch }) {
  const [deletePost] = useMutation(DELETE_POST, {
    onCompleted: () => refetch(),
  });

  function handleDeletePost(id) {
    if (window.confirm("Are you sure you want to delete this post?")) {
      deletePost({ variables: { id } });
    }
  }

  return (
    <div>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
      <button onClick={() => handleDeletePost(post.id)}>Delete</button>
    </div>
  );
}

Refetching Queries with useMutation

Note that we can also utilize the useMutation hook to reexecute our queries through an argument provided to the mutate function, called refetchQueries.

It accepts an array of queries that we want to refetch after a mutation is performed. Each queries is provided within an object, just like we would provide it to client.query(), and consists of a query property and a variables property.

Here is a minimal example to refetch our GET_POSTS query after a new post is created:

function NewPost() {
  const [createPost] = useMutation(CREATE_POST, {
    refetchQueries: [
      { 
        query: GET_POSTS, 
        variables: { limit: 5 } 
      }
    ],
  });

  // ...
}

Using the client with useApolloClient

We can get access to the client across our components with the help of a special hook called use Apollo client. This execute the hook at the top of our function component and we get back the client itself.

function Logout() {
  const client = useApolloClient();
  // client is the same as what we created with new ApolloClient()

  function handleLogout() {
    // handle logging out user, then clear stored data
    logoutUser();
    client.resetStore().then(() => console.log("logged out!"));
    /* Be aware that .resetStore() is async */
  }

  return <button onClick={handleLogout}>Logout</button>;
}

And from there we can execute all the same queries, mutations, and subscriptions.

Note that there are a ton more features that come with methods that come with the client. Using the client, we can also write and read data to and from the cache that Apollo sets up (using client.readData() and client.writeData()).

Working with the Apollo cache deserves its own crash course in itself. A great benefit of working with Apollo is that we can also use it as a state management system to replace solutions like Redux for our global state. If you want to learn more about using Apollo to manage global app state you can check out the following link.

I attempted to make this cheatsheet as comprehensive as possible, though it still leaves out many Apollo features that are worth investigating.

If you want to more about Apollo, be sure to check out the official Apollo documentation.

Download the cheatsheet

Want a quick reference of all of these concepts?

Click to grab the complete PDF cheatsheet

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

Within an afternoon, you will gain the core skills to build your own React and GraphQL projects.

Why you should learn React with GraphQL ?

React is the go-to library for building amazing app experiences with JavaScript. GraphQL, on the other hand, is a tool that gives us a better, more straightforward means of getting and changing our data.

That data could be from a standard database (as we'll be using in our app) or as React frameworks like Gatsby have made possible, even from static files such as markdown files. Regardless of how it's stored, GraphQL makes working with data in our apps better.

We'll see how to leverage the powers of React and GraphQL by creating a social blogging app from start to finish, where you can create, read, edit and delete posts.

You can click here to access the course.

What tools we'll be using ?️

The crash course is meant for developers who are somewhat familiar with React (including the core React Hooks, such as useState and useEffect), but aren't familiar with GraphQL yet.

Basic React knowledge is assumed, but GraphQL knowledge is not required. We'll cover all the core GraphQL concepts you need along the way.

Throughout the course, we'll utilize the following technologies to create our app:

• React (to build our user interface)
• GraphQL (to get and change data in a declarative way)
• Apollo Client (to allow us to use React and GraphQL together)
• Hasura (to create and manage our GraphQL API + database)

To top it off, we'll be using the online IDE CodeSandbox. This will allow us to code our entire application within the browser in realtime, without the need to create any files, folders, or install dependencies on our own.

Creating a GraphQL API from scratch

To get started working with GraphQL, we'll see how to make an entire GraphQL API from scratch that will communicate with our database.

Fortunately, using the (free) service Hasura, this process is very simple and straightforward. Within seconds, we'll see how to create and deploy a complete GraphQL API to the web, which is connected to a Postgres database that will take care of storing our app data.

Click to watch this lecture

Getting familiar with GraphQL

In the second lecture, we'll cover how to write in the GraphQL language using our API's built-in console called GraphiQL.

First, we will create a table in our database for all of our posts data. After which, Hasura will automatically create the queries and mutations we need, which are the names of GraphQL operations that allow us to get and change data in our database.

Throughout this lesson, we'll get very familiar performing queries and mutations in GraphiQL, which will enable us to get entire sets of posts and individual posts, as well as to create, update, and delete our individual post data.

Click to watch this lecture

Connecting React with our GraphQL API using Apollo Client

Now that we're comfortable with using GraphQL and understand its core features, we'll see how to connect it with our React client.

The way that we connect our React app with the GraphQL API we created is through a library called Apollo. We'll see how to set up the Apollo client, by providing the GraphQL endpoint, which points to our API, like so:

import ApolloClient from "apollo-boost";

const client = new ApolloClient({
  uri: "https://react-graphql.herokuapp.com/v1/graphql"
});

With our newly created client, we have the ability to execute any GraphQL operation through React. To do this, however, we need to pass our client to our entire to all of our React components. We do that with the help of the Apollo provider, as you see below:

Click to watch this lecture

Getting posts with useQuery

After setting up our client, we'll see how to execute different GraphQL operations with them, using some special React hooks that come with the package @apollo/react-hooks.

The hook that allows us to query for data with GraphQL is called useQuery. With it, we'll first see how to get and display all of our post data in our homepage.

Additionally, we'll learn how to write our GraphQL queries directly in our JavaScript files with the help of a special function called gql.

import React from "react";
import { useQuery } from "@apollo/react-hooks";
import { gql } from "apollo-boost";

export const GET_POSTS = gql`
  query getPosts {
    posts {
      id
      title
      body
      createdAt
    }
  }
`;

function App() {
  const { data, loading } = useQuery(GET_POSTS);

  if (loading) return <div>Loading...</div>;
  if (data.posts.length === 0) return <Empty />;

  return (
    <>
      <header className={classes.header}>
        <h2 className={classes.h2}>All Posts</h2>
        <Link to="/new" className={classes.newPost}>
          New Post
        </Link>
      </header>
      {data.posts.map(post => (
        <Post key={post.id} post={post} />
      ))}
    </>
  );
}

Creating and editing new posts with useMutation

After that, we'll see how to create new posts with the useMutation hook. In order to do this, we'll take a look at how to work with GraphQL variables to pass our mutation dynamic values that will change with each execution.

Following that we'll take a look at how to edit our posts. To do so, we'll need to fetch an individual post and display it within our form, so that our user can make changes to the data. Then we'll need to execute a mutation that will perform the update, based on the posts id.

Click to watch this lecture

Handle loading and errors

In the following lecture, we'll cover some essential patterns for handling the process of loading our data.

It's important to do so when we execute a mutation, to make sure we don't submit our forms multiple times as our mutation is being executed. We'll also take a look at how to handle errors in the event that our mutation is not executed correctly.

Click to watch this lecture

Deleting posts

Finally, we'll cover how to delete posts from our app. First, we'll confirm that the user wants to actually delete the post that they've made, then perform the mutation.

Additionally, we'll take a look at how to update our UI in response to mutations with the helpful refetch function that Apollo gives us. It will enable us to re-execute a query on demand. In this case, we'll do it after the delete mutation has been successfully performed.

Click to watch this lecture

Become a Professional React Developer

React is hard. You shouldn't have to figure it out yourself.

I've put everything I know about React into a single course, to help you reach your goals in record time:

Introducing: The React Bootcamp

It’s the one course I wish I had when I started learning React.

Click below to try the React Bootcamp for yourself:

Click to get started

Chances are, like many people, you’re coming to Apollo and GraphQL from a REST API background. Yet as you begin to explore the working examples of this stack and the different ways to implement it, you will no doubt be tripped up on a multitude of differences, whether it’s Apollo’s Libraries, or the entire ‘get your data as you want it’ mentality around GraphQL and Apollo’s render components.

What I want to do in this article is help address two of the key issues when writing a mutation. This primarily targets HOC implementations, however it is more or less the same for the render components, tweaking object keys to props instead.

Specifically, we will be jumping straight into the optimisticResponse along with the update parameters of your HOC mutation. It is my hope that this will make you more aware of what options you have when it comes to implementing a mutation as a prop function.

Important: If you are only just getting started with Apollo, I wholeheartedly implore you to implement their render components that they released around version 2.1. HOCs are soft deprecated and as such, are missing a lot of their documentation, as mentioned by a few people here.

Optimistic Response

optimisticResponse is the way we manage if our app is online or not along with the status of our requests to the DB.

If we mutate our database without a connection, the optimistic response allows it to exist with variables that we reasonably expect.

For example, if we assume that we will add this user to the db:

{    userId: 123,    firstName: "Lachlan",    lastName: "Young",    status: "Hungry"}

We would want to update our user details with the above data. However, because of the way our mutations work (and this is specifically for HOCs but can be applied to Render components too), there is a lifecycle to the mutation, going from loading, to success/fail/can’t connect.

If at any point the mutation fails but does not error, your Apollo client knows that this was because of something other than a bad object. By this I mean it takes into account your offline status, the status of the request, and it will instead render that user to the user details component, because it assumes it is valid. Therefore your client is being optimistic.

When you connect to the internet again or reach your DB, it will update the response with the valid data. Inside of that response you can handle stuff like userId’s which you generate on the client, therefore updating my hardcoded id of 123, to a UUID.

If we weren’t online we could still see and interact with the request as expected and any changes would be queued to then mutate the server upon reconnecting.

That’s an optimistic response.

Update

As for how to handle the response from the database, you actually have access to a property called update, and for HOCs it looks like this:

update: (proxy, { data: { myDetails } }) => {    try {        // Read the data from our cache for this query.        const data = proxy.readQuery({             query: gql`${GET_MY_DETAILS}`        });

        // Add our new request from the mutation to the end.        data.getMyDetails.push(myDetails);

        // Write our data back to the cache.        proxy.writeQuery({             query: gql`${GET_MY_DETAILS}`,            data        });    } catch (err) {        console.log('Error updating the cahche: ', err.message);    }}

Essentially this comes after the optimisticResponse field in the mutation. It directly handles what happens after you receive a response, taking it from the top it has proxy and data as it’s two arguments. Proxy is quite literally our client, however for some configurations you may be better served referencing it as the cache. Data is the response from the mutation. I’ve deconstructed it, in this case, to explain the myDetails object further.

myDetails consists of everything in the user object above, but the id will now be a valid UUID instead of 123. We then use the apolloClient’s methods for reading and writing and read the details we have saved in our cache. From there we add our new details and re-write them to the cache. This way after I navigate back to my details from the input page, my new details will instantly be available because they are the point of truth in the cache.

Additional Information

As of writing this, all the render props documented here, or seen below for longevitiy, can be applied to your HOC mutation. As I mentioned in the introduction to this article, the HOC documentation has indeed been deprecated. However, the options given below can all be implemented as keys to the HOC object.

Mutation Props 4/12/2018

Thank you very much for reading. You can usually see me floating around the Apollo Slack in either the #React-Apollo or #Apollo-Client channels. To register for the slack and get more specific advice, click here.