Using GraphQL Code Generator For Type-Safe GraphQL Clients

Using GraphQL together with TypeScript can have huge advantages, as you can use your GraphQL schema to create TypeScript type definitions and even code that fetches data from the GraphQL server.

This is incredibly powerful. Why is that? Basically it means we can have TypeScript types that match our GraphQL types and operations. An important nuance is that TypeScript has a set of types and GraphQL has a set of types. It might take a minute to understand, but these are different things, as GraphQL and TypeScript have a similar type system with slightly different nuances. What exactly is what we will discover in this article!

GraphQL API#

To generate TypeScript type definitions and code from GraphQL, we first need to have a schema. For this you'll use the Rick and Morty API that is publicly available, and based on the popular television show.

When you open the GraphQL Playground for the Rick and Morty API you can use multiple operations like queries and mutations.

Let's try this out, by pasting the query below in the Explorer:

This will result in a JSON response that consists of all the characters in the show and their name and gender.

Great! Using the Rick and Morty API as starting point we can now use this with TypeScript and autogenerate some code.

Requesting GraphQL from your App#

To get this data from the GraphQL API into your application you need to fetch the data using the query. For this you could use a regular HTTP-request or any of the popular GraphQL clients.

For this example we're using the library graphql-request that's very lightweight and requires just a few lines of code. After installing it from NPM, you can fetch data from the Rick and Mory API like this:

But the data that you receive from the API doesn't have any type definitions that you can use in TypeScript. Instead of adding them manually, the library GraphQL Code Generator can be used.

GraphQL Code Generator #

Generating the TypeScript type definitions and code can be done with GraphQL Code Generator is a CLI tool that generates TypeScript typings out of any GraphQL schema.

Let's create an application to fetch the Github info using TypeScript code generated from the GraphQL schema. Installing GraphQL Code Generator can be done with npm or Yarn, but first you need to add graphql as a dependency.

And @graphql-codegen/cli and related plugins as a dev dependency:

You've now installed everything you need to generate the type definitions from the GraphQL API.

But to use GraphQL Code Generator you need to add a configuration file called codegen.yaml that specifies the url to the GraphQL API and the plugins that must be used:

After adding the configuration file you can run the command graphql-codegen from the command line, in the same directory as the configuration file was added. This will now create a new types.ts file containing all the TypeScript type definitions based on the schema of the Rick and Morty API.

This means that you can use this to have a type for the data returned by graphql-request. In your query you requested the characters that are represented as a type called Characters:

Pretty straightforward! Of course, there are many more features GraphQL Code Generator that you could use. In the book Fullstack GraphQL you can find more working examples, including a guide to generate GraphQL client code from your GraphQL schema.