Senior Software Engineer I

Scott Jones

At EF Go Ahead Tours Engineering, we use a tool called 

 often. Since we use TypeScript and GraphQL, it saves us a lot of time since we can create TypeScript types from our GraphQL schema. Let's set up a basic GraphQL schema to show how it works:

const typeDefs = gql`
    type Query {
        cart(id: ID!): Cart
        carts: [Cart!]
    }
    
    type Cart {
        items: [Product!]
        grandTotal: Int!
    }

    type Product {
        sku: String!
        price: Int!
    }
`

Pretty simple, we have a two queries and a basic eCommerce model. This sets up our contract with our API. Let's generate our application types. We can do this by installing the needed packages and the plugins for typescript:

npm i @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-resolvers

All of these packages gives us the functionality to generate both types and a typed resolver, with a pretty minimal configuration, as specified in a YAML file. Let's set one up:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers

This is an incredibly barebones configuration, only meant to show the TypeScript type generation, more details about configuration can be found 

All that's left is to run our generator and see what types we are able to use!

  "scripts": {
    "generate": "graphql-codegen"
  }  

at which point the command can be run with 

After this, we can see what types are generated in the 

 file! Having this tool is incredibly helpful for both back end and front end work, since our types can be generated from our GraphQL schema, which introduces coupling of the schema definition and the types that we can use within our apps. This makes GraphQL schemas 

, which means that the data and the types of that data is now available for us to use in TypeScript!

graphql-codegen works for both server and client side. Let's implement a basic resolver using our newly generated types:

import { Resolvers } from "./src/generated/types.ts"

export const resolvers: Resolvers => {
    Query: {
        cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
    }
}

 type from our generated schema, which gives us typechecking for all of our resolvers! This also includes typechecking for our parent type, our field arguments, and our context. Super easy! The package also splits out each individual resolver so one could do:

// ./src/cartResolvers.ts
import { CartResolvers } from "./src/generated/types.ts"

export const cartResolvers: CartResolvers => {
    cart(parent, args, context) {
            console.log(args)
            return null
        },
        carts(parent, args, context) {
            console.log(args)
            return []
        }
}

export const resolvers: Resolvers => {
    Query: {
        ...cartResolvers
    }
}

This makes creating typechecked resolvers with IntelliSense in VS Code very easy and guarantees static types from your schema. How can this tool also help us with the front end? After all, one of the benefits of using GraphQL is that we can query only the data we need. We can do this with a very minimal configuration update in our client side app, copying it from our GraphQL server configuration:

schema: "./src/typeDefs.ts"
generates:
  src/generated/types.ts
    plugins:
      - typescript
      - typescript-resolvers
+     - typescript-react-apollo
+     - typescript-operations
+     - fragment-matcher
+ documents: "src/graphql/**.{ts, tsx, graphql}"

This configuration will scrape all of our graphql, ts, and tsx files in our 

 file. We'll also need to install the extra plugins that this config requires:

npm i @graphql-codegen/typescript-operations @graphql-codegen/fragment-matcher @graphql-codegen/typescript-react-apollo

At EF Go Ahead Tours we use the first one quite a bit in most typical front-end applications, since we leverage a ton of GraphQL. A typical React component that fetches a cart by ID from our GraphQL server with a search parameter would look like:

// src/graphql/cart.graphql

query FindCart($id: ID!) {
    cart(id: $id) {
        items
        grandTotal
    }
}
        
// src/checkout/cart.tsx
import React from "react";
import { useFindCart } from "./src/generated/typedefs.ts";
import { Item } from "./Item";
import { Spinner } from "../shared/Spinner";

export const Cart: React.FC = () => {
    const cartId = new URLSearchParams(window.location.search).get("cartId");
    const { data, loading } = useFindCart({
        variables: {
            id: cartId ?? ""
        }
    });

   if (loading) {
        return <Spinner />
    }

    return (
        <>
            <h2>{data.grandTotal}</h2>
            {data?.items.map((item) => <Item item={item} />
        </>
    );
}

Where all of our queries and mutations, along with their variables are typechecked. This makes it very easy to build services alongside clients that consume those services, while maintaining type checking between the both of them. Graphql-codegen is an invaluable tool for us developers here at EF Go Ahead Tours. Without it we would never have been able to build services and front end applications with the speed of sharing types between client and server without the manual work of migrating types and the developer experience that using graphql-codegen affords us.

Scott Jones

GraphQL Codegen: What is it?