In this post, I want to explain something that tripped me up for a long time: how to generate TypeScript types from a GraphQL server.

"Wait, TypeScript types and GraphQL types are different??"

They are! In fact, you even have types for your 

, which is extra confusing. Let me try to clarify.

So, in your GraphQL server you might expose a 

 consumes this API it is over HTTP -- but if we're using TypeScript, it would be nice to have 

*and they both have their own, separate, types

 server. And it's super handy because not only is your code type-checked, but your editor will also help you autocomplete.

Generating GraphQL TypeScript Types by Hand (lol don't do this)

At first, you might try writing these types by hand, but this will just drive you crazy to maintain by hand as your app grows.

However, in a large scale production application, there could be hundreds of GraphQL endpoints & types. Take a look at 

, no joke, there are almost 1,000 endpoints & types. Creating TypeScript definitions for those (by hand) would be a nightmare!

Not only that, a change in the server means you will have to find and update your TypeScript definitions over and over again. Ew.

 GraphQL API already has types defined in the schema. Wouldn't be great if there is something that can translate GraphQL types into TypeScript automatically?

Ladies & gentleman, let me introduce to you, 

The Apollo CLI is a robust command line interface that allows for a variety of different things such as schema validation, generate static types, and etc. And we'll use this tool to auto-generate TypeScript definitions from our GraphQL API. Here's how:

To use the Apollo CLI, we can install it globally with the following command:

There are two commands we are especially interested in:

We'll set up both of these steps as two separate script commands in our application's 

{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "",
    "codegen:generate": ""
  }
  // ...
}

To download the schema, we'll need to run the 

 command and specify the options we would want. In our case, we'll specify the single minimum option we need - the endpoint and pass in the value of our local GraphQL endpoint (

{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "npx apollo client:download-schema --endpoint=http://localhost:9000/api",
    "codegen:generate": ""
  }
  // ...
}

After a brief period, we'll notice success messages that state 

 file be generated that represents our entire GraphQL schema!

With the GraphQL schema available in our app, we can now look to generate the static types for the 

 mutation in our GraphQL API. This can be done with the Apollo CLI 

We'll specify a few options as we set up the script.

 option, which is used to specify the path to the schema file in our 

 file is in the root of our project, the value for the 

apollo client:codegen --localSchemaFile=schema.json

 option which is used to state the files that contain the GraphQL operations we'll want to generate static types for. In my case, all of my GraphQL requests live in TypeScript files within my 

 folder. There fore, I'll specify a value of 

 which entails looking through our entire 

apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx

 option, which is required and allows us to specify which code generator we'd like to use. 

 are all different options but in our case we're interested in the 

apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx --target=typescript

{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "npx apollo client:download-schema --endpoint=http://localhost:9000/api",
    "codegen:generate": "npx apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx --target=typescript"
  }
  // ...
}

Generating query files with 'typescript' target - wrote 3 files

By default, the Apollo code generator creates static typings for the GraphQL documents it finds in 

client/
  src/
    sections
      Listings/
        __generated__/
          DeleteListing.ts
          Listings.ts

If we take a look at one of these auto generated files, we can see TypeScript interfaces for the return data and input variables!

/* tslint:disable */
/* eslint-disable */
// This file was automatically generated and should not be edited.

// ====================================================
// GraphQL mutation operation: DeleteListing
// ====================================================

export interface DeleteListing_deleteListing {
  __typename: "Listing";
  id: string;
}

export interface DeleteListing {
  deleteListing: DeleteListing_deleteListing;
}

export interface DeleteListingVariables {
  id: string;
}
```
```typescript
/* tslint:disable */
/* eslint-disable */
// This file was automatically generated and should not be edited.

// ====================================================
// GraphQL query operation: Listings
// ====================================================

export interface Listings_listings {
  __typename: "Listing";
  id: string;
  title: string;
  image: string;
  address: string;
  price: number;
  numOfGuests: number;
  numOfBeds: number;
  numOfBaths: number;
  rating: number;
}

export interface Listings {
  listings: Listings_listings[];
}

 you'll get up to speed with this whole stack really quickly. We've organized the course so that you can skip around if you just want to learn a specific part, but we also build the whole production-ready app if you want to walk through step-by-step. Check out 

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Generate TypeScript Types from GraphQL</h1><p>In this post, I want to explain something that tripped me up for a long time: how to generate TypeScript types from a GraphQL server.</p><h2 class="heading-anchor-text" id="wait,-typescript-types-and-graphql-types-are-different??"><span>"Wait, TypeScript types and GraphQL types are different??"</span><a class="d-inline" href="#wait,-typescript-types-and-graphql-types-are-different??">#</a></h2><p>They are! In fact, you even have types for your <em>queries</em>, which is extra confusing. Let me try to clarify.</p><p>So, in your GraphQL server you might expose a <code>User</code> object. <code>User</code> has fields like <code>id</code>, <code>email</code>, <code>username</code>, <code>profileImageUrl</code> etc. When your <em>client</em> consumes this API it is over HTTP -- but if we're using TypeScript, it would be nice to have <em>TypeScript</em> types that match the <em>GraphQL</em> types.</p><p>So again, </p><ul><li><p>GraphQL is "protocol" and language with a definition. </p></li><li><p>TypeScript is a programming language</p></li></ul><p><strong>*and they both have their own, separate, types</strong>. </p><p>This post shows you how to generate <em>TypeScript</em> types from your <em>GraphQL</em> server. And it's super handy because not only is your code type-checked, but your editor will also help you autocomplete.</p><h2 class="heading-anchor-text" id="generating-graphql-typescript-types-by-hand-lol-dont-do-this"><span>Generating GraphQL TypeScript Types by Hand (lol don't do this)</span><a class="d-inline" href="#generating-graphql-typescript-types-by-hand-lol-dont-do-this">#</a></h2><p>At first, you might try writing these types by hand, but this will just drive you crazy to maintain by hand as your app grows.</p><p>However, in a large scale production application, there could be hundreds of GraphQL endpoints &amp; types. Take a look at <a href="https://docs.github.com/en/free-pro-team@latest/graphql/reference" rel="noopener noreferrer nofollow">GitHub's v4 GraphQL API</a>, no joke, there are almost 1,000 endpoints &amp; types. Creating TypeScript definitions for those (by hand) would be a nightmare!</p><p>Not only that, a change in the server means you will have to find and update your TypeScript definitions over and over again. Ew.</p><p>Of course <strong>every</strong> GraphQL API already has types defined in the schema. Wouldn't be great if there is something that can translate GraphQL types into TypeScript automatically?</p><p>As you've probably predicted, there is.</p><h2 class="heading-anchor-text" id="apollo-cli"><span>Apollo CLI</span><a class="d-inline" href="#apollo-cli">#</a></h2><p>Ladies &amp; gentleman, let me introduce to you, <a href="https://github.com/apollographql/apollo-tooling" rel="noopener noreferrer nofollow">Apollo CLI</a>.</p><p>The Apollo CLI is a robust command line interface that allows for a variety of different things such as schema validation, generate static types, and etc. And we'll use this tool to auto-generate TypeScript definitions from our GraphQL API. Here's how:</p><p>To use the Apollo CLI, we can install it globally with the following command:</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-rQ6OlTfTbGNkM5U_K30V1" id="cm-rQ6OlTfTbGNkM5U_K30V1">npm install -g apollo</textarea><p>There are two commands we are especially interested in:</p><ol><li><p><strong>download our GraphQL schema</strong> and save a copy of it in our client</p></li><li><p><strong>auto generate the TypeScript definitions</strong> from our schema</p></li></ol><p>We'll set up both of these steps as two separate script commands in our application's <code>package.json</code> file. We'll label these scripts <code>codegen:schema</code> and <code>codegen:generate</code>.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-VLZGBVjOBctMGmfQCaEDX" id="cm-VLZGBVjOBctMGmfQCaEDX">{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "",
    "codegen:generate": ""
  }
  // ...
}</textarea><h3 class="heading-anchor-text" id="downloading-the-schema"><span>Downloading the Schema</span><a class="d-inline" href="#downloading-the-schema">#</a></h3><p>To download the schema, we'll need to run the <code><a href="https://github.com/apollographql/apollo-tooling#apollo-clientdownload-schema-output" rel="noopener noreferrer nofollow">apollo client:download-schema</a></code> command and specify the options we would want. In our case, we'll specify the single minimum option we need - the endpoint and pass in the value of our local GraphQL endpoint (<code>http://localhost:9000/api</code>).</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-c63teUYpIhuZl93HJJ4ia" id="cm-c63teUYpIhuZl93HJJ4ia">{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "npx apollo client:download-schema --endpoint=http://localhost:9000/api",
    "codegen:generate": ""
  }
  // ...
}</textarea><p>We'll run the newly created <code>codegen:schema</code> script in our command line.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-4psAkCZEkdjJhz2n3WIX8" id="cm-4psAkCZEkdjJhz2n3WIX8">npm run codegen:schema</textarea><p>After a brief period, we'll notice success messages that state <code>Loading Apollo Project</code> and <code>Saving schema to schema.json</code>.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210203230744535_apollo-client-codegen.png" attachmentid="94509fa9-c975-4ad3-bb07-bbd32eb61b04" contenteditable="false" data-width="2294" data-height="630"><div></div></figure><p>If we look at the root of our <code>client/</code> directory, we'll notice a <code>schema.json</code> file be generated that represents our entire GraphQL schema!</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210203230806042_apollo-client-codegen-schema.png" attachmentid="9ed389e2-539e-4214-9b2e-b6c20e972bab" contenteditable="false" data-width="2400" data-height="1546"><div></div></figure><p>With the GraphQL schema available in our app, we can now look to generate the static types for the <code>listings</code> query and <code>deleteListing</code> mutation in our GraphQL API. This can be done with the Apollo CLI <code>client:codegen</code> command.</p><h3 class="heading-anchor-text" id="generating-the-typescript-types"><span>Generating the TypeScript Types</span><a class="d-inline" href="#generating-the-typescript-types">#</a></h3><p>We'll specify a few options as we set up the script.</p><p>The first option we'll add is the <code>--localSchemaFile</code> option, which is used to specify the path to the schema file in our <code>client/</code> directory. Since the <code>schema.json</code> file is in the root of our project, the value for the <code>--localSchemaFile</code> option will be <code>schema.json</code>.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-t-rbZayo24ymtJZ08R49J" id="cm-t-rbZayo24ymtJZ08R49J">apollo client:codegen --localSchemaFile=schema.json</textarea><p>The second option we'll specify is the <code>--includes</code> option which is used to state the files that contain the GraphQL operations we'll want to generate static types for. In my case, all of my GraphQL requests live in TypeScript files within my <code>src/</code> folder. There fore, I'll specify a value of <code>src/**/*.tsx</code> which entails looking through our entire <code>src/</code> folder and for any files that have the <code>.tsx</code> file extension.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-9e4uyUVaICAVdGgLcDZcJ" id="cm-9e4uyUVaICAVdGgLcDZcJ">apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx</textarea><p>The final option we'll specify is the <code>—-target</code> option, which is required and allows us to specify which code generator we'd like to use. <code>swift</code>, <code>flow</code>, <code>scala</code> are all different options but in our case we're interested in the <code>typescript</code> option.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-vuJXn3XVu-TU016oMbDAr" id="cm-vuJXn3XVu-TU016oMbDAr">apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx --target=typescript</textarea><p>We'll have the above <code>apollo</code> command as part of the <code>codegen:generate</code> script command in our application.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-2JANEB4dI6o5Y-H_BWSs2" id="cm-2JANEB4dI6o5Y-H_BWSs2">{
  // ...
  "scripts": {
    // ...
    "codegen:schema": "npx apollo client:download-schema --endpoint=http://localhost:9000/api",
    "codegen:generate": "npx apollo client:codegen --localSchemaFile=schema.json --includes=src/**/*.tsx --target=typescript"
  }
  // ...
}</textarea><p>We can now run the newly created <code>codegen:generate</code> command in our terminal.</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-faQrFjZuVxnVlRryMWXhu" id="cm-faQrFjZuVxnVlRryMWXhu">npm run codegen:generate</textarea><p>Upon success, we'll see the <code>Loading Apollo Project</code> message followed by <code>Generating query files with 'typescript' target - wrote 3 files</code>.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20210203230915413_apollo-client-codegen-generate.png" attachmentid="32838769-3f29-4bf7-9ade-e5e71a89c26c" contenteditable="false" data-width="2294" data-height="630"><div></div></figure><p>By default, the Apollo code generator creates static typings for the GraphQL documents it finds in <code>__generated__/</code> folders. For example:</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-seQ7QrR-YIFDmaBUHkXee" id="cm-seQ7QrR-YIFDmaBUHkXee">client/
  src/
    sections
      Listings/
        __generated__/
          DeleteListing.ts
          Listings.ts</textarea><p>If we take a look at one of these auto generated files, we can see TypeScript interfaces for the return data and input variables!</p><textarea data-iscodemirror="true" data-mode="text/jsx" data-uniqueid="cm-3MTq0" id="cm-3MTq0">/* tslint:disable */
/* eslint-disable */
// This file was automatically generated and should not be edited.

// ====================================================
// GraphQL mutation operation: DeleteListing
// ====================================================

export interface DeleteListing_deleteListing {
  __typename: "Listing";
  id: string;
}

export interface DeleteListing {
  deleteListing: DeleteListing_deleteListing;
}

export interface DeleteListingVariables {
  id: string;
}
```
```typescript
/* tslint:disable */
/* eslint-disable */
// This file was automatically generated and should not be edited.

// ====================================================
// GraphQL query operation: Listings
// ====================================================

export interface Listings_listings {
  __typename: "Listing";
  id: string;
  title: string;
  image: string;
  address: string;
  price: number;
  numOfGuests: number;
  numOfBeds: number;
  numOfBaths: number;
  rating: number;
}

export interface Listings {
  listings: Listings_listings[];
}</textarea><h2 class="heading-anchor-text" id="get-up-to-speed-with-tinyhouse"><span>Get Up To Speed with Tinyhouse</span><a class="d-inline" href="#get-up-to-speed-with-tinyhouse">#</a></h2><p>In <a href="https://www.newline.co/tinyhouse" rel="noopener noreferrer nofollow">Tinyhouse,</a> you'll get up to speed with this whole stack really quickly. We've organized the course so that you can skip around if you just want to learn a specific part, but we also build the whole production-ready app if you want to walk through step-by-step. Check out <em><a href="https://www.newline.co/tinyhouse" rel="noopener noreferrer nofollow">Tinyhouse: a Fullstack React Masterclass</a></em></p><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Generate TypeScript Types from GraphQL

Tags

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript