Why You Should Use GraphQL-Code Generator with React and GraphQL

What is Graphql-Code Generator (CodeGen)?

GraphQL-CodeGen is a CLI that can generate code from your GraphQL operations and schema. In React projects using typescript operations, it is very helpful to map GraphQL schema into interfaces.  GraphQL can also generate hooks from operations.

Why use Graphql-Code Generator?

Using GraphQL in a React project can intimidate developers since doing it properly often obliges much repetitive work. As a result, GraphQL is just as often bypassed - and all the good stuff that comes with it.

In a standard React project that uses GraphQL operations, you will write your queries as string constants, then pass this query into a useQuery hook which will return the data you were requesting. If you are a typescript user, you should also write interfaces that will describe what variables are used in your query and what you will get in response. You must always remember which field can be nullable. If something changes in your schema or query, then this change must be reflected in all places. 

Although you can try using other operations and fragments, they will not solve all problems.

This strikes me as doing rather a lot for the sake of fetching data, which is why many job developers struggle with GraphQL. Yet all that is required is a helper tool. 

Enter code generators. Using the GraphQL code generator in your project can make development faster, easier and consistent.

Graphql-CodeGen helps by doing this repetitive work, leaving you only to writing queries, mutations or fragments, and using hooks already typed. Thanks to GraphQL-CodeGen, development time is shortened considerably as there is less to write manually with fewer places for typos. It’s also very consistent in that the generated code is always reflected in your GraphQL schema. 

What are the benefits of Graphql-Code Generator?

By adding the GraphQL code-generating step to your code-build process, you will gain some level of integration testing. You will also be obliged to use operations that are available in the way for which they were created. This is because CodeGen uses a schema already deployed in one of your environments. You just have to tell it where this schema is.  If, for example, you deploy your app to a staging client environment where the staging backend is not up to date and therefore lacks the required endpoints, the build will naturally fail. The  GraphQL code-generating mechanism is one that has rescued me countless times when trying to release new features on a production whose backend is only functioning on staging!

Where to use GraphQL-Code Generator?

Quite simply, where your project uses GraphQL operations. Since the package features several plugins and extensions (for typescript, Java, C#, etc.), this is the only requirement. On the frontend, it supports React, Vue and Angular js.

In this article, we will focus on a React project written in typescript as this is the most popular library to use with GraphQL.

How to use GraphQL-Code Generator

To begin the installation, you'll need to add some specific dependencies concurrently. For a comprehensive list of these dependencies, you can refer to the official installation guide.

Then, you'll need to add a codegen.yml file to your project, which will serve as your GraphQL-CodeGen configuration. You can find an example of how this file should look in the official Codegen configuration guide.

Notice how a config schema is loaded from ${REACT_APP_API_ENDPOINT} which is an env variable.

This will enable the use of the same schema the client uses.

From then on we can use the generator -- but we're not done yet.

The next step is to add specific scripts to your package.json file. You can find examples of the types of scripts you'll need to add in the official Codegen setup guide.

From this point, whenever you want to generate typings manually, you will run yarn CodeGen. Also, you may notice a `dev` script running your project and CodeGen in watch-mode. As a result, you no longer have to run CodeGen every time you change something in your GraphQL operations or fragments. Instead, your project will automatically reflect these changes and instantly throw errors where there are any. 

Next, I usually add a generated file in src/generated/graphql.ts to .gitignore. This way, the generated file will not be tracked. But this is also why it is important to run CodeGen before building your project: it will afford you a small level of integration testing since the generated file contains typings already.  Admittedly, this is not testing, but getting errors in compile-time can still be very advantageous.

A final benefit is the generation of enums you can use in your code.

And that's it. From here you can write your operations anywhere in the src folder. Files will then be detected and used to create desired typings. 

For more advanced use cases, I recommend visiting documentation. There you will find more information, plugins, tutorials and snippets. Have a look at https://www.graphql-code-generator.com/. 

Of course, GraphQL-CodeGen is just one of the many programming wonders expertly employed at Startup House. If you'd like to find out more about what our development teams can do, feel free to reach out to hello@start-up.house.