How to Use GraphQL With React
What do we need when we want to create a simple web app in 2022? We need a client side application, a server and some kind of database. Quite simple, right? Nowadays, these layers are essential to provide a marvelous experience to all the people who will become users of our app. What's the app actually? I will go as classic as possible. Yes, it will be a To Do app!
In this article, I assume that you (the reader) have some background knowledge about NodeJS, React, and Typescript. The goal of this blog is to show how we can kick off GraphQL using these technologies without deep-diving into them.
To keep it simple we only focus on the App and Server communication which is created using GraphQL instead of REST. GraphQL is able to send data through HTTP too, but it is not mandatory. As you’ve already figured it out we will leave the classical database part out and in our case, this is an in-memory solution. Just note that it will reset on every server rerun. Let’s begin.
Side note: You can jump over all the explanations and run the finished app that can be found at the end of the article.
What is GraphQL?
Your first thought must be “What is GraphQL?”. GraphQL is a query language for APIs which provides a complete and understandable description of the data. It has the ability to give the clients the power to ask for all the data they want and nothing more.
I was not telling the full story when I stated that it is used instead of REST. However, in my implementation this is true but not in many other cases. For real, GraphQL is a new layer in your architecture that can hide many data sources like REST APIs, MongoDb or PostgreSQL connections, etc. behind a single point of truth: one endpoint. The client can get all the data it needs in a single request.
GraphQL APIs are organized in terms of types and fields, not endpoints. So it uses types to ensure clients only ask for what’s possible and they provide clear and helpful errors. Apps can use types to avoid writing parsing code manually.
Okay, now you get the idea. We will use a GraphQL library for the server and for the app. It’s called Apollo.
This backend is easy and can be implemented in one single index.js file. To start the project just create a directory with your preferred name and run the following commands:
Type definitions and database
To begin with, we have to define what kind of data-, query- and mutation types can be provided by the server. The data type is clear. But the other two will need some explanation. GraphQL calls any request that asks data from the backend a query. And mutations are used as the rest of the operations from the CRUD, these are the requests that create, update or delete resources.
Type definitions tell us and the IDE information but they don't exactly explain how they should work. This is why resolvers exist. They include how to query and mutate the data and where the data can be found.
Setup and start
Last but not least, we have everything to boot the server up with some configuration and a method call.
To finish our application let’s talk about the other side of the HTTP, the React application that we will create to be the UI to show to-do list items, and it lets us interact with them. With these few commands to run you’ve got a base skeleton of the app:
This may be familiar from the server. We have written some type definitions for the GraphQL that are actually needed here too. It can be shared via some library or monorepo but as I mentioned I chose an easy-to-create but more-difficult-to-maintain way. I copied those types.
Similarly to the Apollo server, the client has to be configured the following way:
Because this is a React app we should let React know about the Apollo Client that was configured above through the help of a provider.
And here is the fun part. We’ve arrived at where we are able to run queries and mutations (and subscriptions but we skip those this time) against that single endpoint. We will use React hooks from the Apollo Client library called useQuery for the queries and useMutation for the mutations. These hooks take two parameters, one GraphQL query, or mutation and one configuration object. UseQuery gives back an object containing the data or error and a loading boolean value. At the same time, useMutation gives back an array that contains the mutation function that we need to call with parameters, and a similar object to useQuery's returned value as the second value of the array. Let me show you how:
You may notice that configurational object with one property in mutations. RefetchQueries is an array of objects referencing queries (DocumentNode objects parsed with the gql function) or an array of names as strings of queries you've previously executed. By including this, it lets your app refetching certain queries after a particular mutation. GraphQL does not do refetching by default.
GraphQL is different in many aspects of the way we use REST APIs. For example, the use of only one endpoint would seem strange instead of many, and that we have type definitions instead of a swagger document.
Requests are specified in a specific language in contrast to REST’s query parameters, path variables, and JSON objects in their body. And we have not talked about the responses yet. Responses via HTTP using GraphQL always gives back HTTP 200 status code (and sometimes not but this is not GraphQL's fault). These other status codes may indicate other problems with the server or the communication channel.
What if GraphQL gives an error? It sends an error property within a JSON object that clearly explains what exception occurred. So it doesn’t rely on HTTP, and it is not as verbose in that way but in every system, it always works the same. Which is good, to be honest.
At the end of the day it doesn't matter if your system will use GraphQL or REST APIs. They can serve the same purpose. Both have advantages and disadvantages that can help you vote for one or the other. However, I can tell that it was quite easy to pick up GraphQL to start a new project with it. Of course the Apollo libraries were handy and they boosted the implementation. Let's be honest, when was the last time we created something purely using the feature set of the languages?
GraphQL is different from REST, and it can be unusual for those who have never used it before. But every tech stack has its own rules that we can learn and understand. If we are able to abstract its rule set from REST’s then GraphQL could be a pretty great tool in our arsenal.