[{"id":"cG9zdDo4NjM=","slug":"a-sane-and-efficient-guide-for-consuming-graphql-endpoints-in-typescript","title":"A sane and efficient guide for consuming GraphQL endpoints in Typescript","content":"\n

GraphQL is becoming common practice in the wild, while I feel the workflow with Typescript is still not straight forward. I want to propose one way to go about it and hopefully make your next Typescript GraphQL project a joy to work with!
Lets dive deeper 🤿.

\n\n\n\n

I created a tiny companion repository if you want to check out the code and try it out.
Or check out the finished demo.

\n\n\n\n

\"\" — Photo by Clayton Robbins on Unsplash

\n\n\n\n

Intro

\n\n\n\n

First we need to decide on what do we want (and probably need)

\n\n\n\n

Editor support for syntax highlighting gql and .graphql files.
Strict type safety for our client.
Easy tooling & workflow

\n\n\n\n

So our workflow will look something like this:

\n\n\n\n

GrapQL API -> Schema -> Queries & Mutations -> Typescript -> Client

\n\n\n\n

For this article we’ll build a minuscule one pager using the SpaceX Land GraphQL API to display some space travel data.

\n\n\n\n

Editor setup

\n\n\n\n

The setup will be be for VSCode. For that we first install the GraphQL extension. This will enable us to have warnings and autocompletion inside of gql tags and .graphql files.

\n\n\n\n

We need to add a .graphqlrc.yml file at the root with the following content:

\n\n\n\n

schema: https://api.spacex.land/graphql/

\n\n\n\n

Writing Queries & Mutations

\n\n\n\n

Now onto the real stuff.
We want to take our endpoint, generate types and queries from it that can then be used by Typescript safely. To do that we will:

\n\n\n\n

Setup generators for Schema, Queries, Mutations & SDK.
Write some Queries & Mutations
Generate the SDK
Consume the SDK

\n\n\n\n

Setup

\n\n\n\n

There is this amazing project called @graphql-codegen which is a collection of tools for helping you generating various things from GraphQL. Let’s install:

\n\n\n\n

# Generators\npnpm i -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-graphql-request\n# For the SDK\npnpm i -D graphql graphql-request graphql-tag

\n\n\n\n

I will assume my GraphQL stuff will live under ./src/lib/gql

\n\n\n\n

We will create a top level configuration file to handle all of our generation step called codegen.yaml. Ignore the config option for now, I will explain that later

\n\n\n\n

schema: https://api.spacex.land/graphql/\ndocuments: \"src/**/*.graphql\"\ngenerates:\n  ./src/lib/gql/gen.ts:\n    plugins:\n      - \"@graphql-codegen/typescript\"\n      - \"@graphql-codegen/typescript-operations\"\n      - \"@graphql-codegen/typescript-graphql-request\"\n    config:\n      maybeValue: \"T\"\n      typesPrefix: GQL\n      immutableTypes: true\n      useTypeImports: true\n      avoidOptionals: true

\n\n\n\n

The property schema does not need an explanation.
generates has 3 plugin enabled, one for the general types, another for queries and mutations and the last one to generate us a ready to use SDK and will save it under ./src/lib/gql/gen.ts.
documents is a glob that will find all our GraphQL files we write and generate the according code.

\n\n\n\n

Creating Queries

\n\n\n\n

Now let’s create a src/lib/gql/root.graphql file and write some queries, all autocompleted of course!

\n\n\n\n

query LaunchpadsMany {\n  launchpads(limit: 10) {\n    id\n    name\n    location {\n      name\n    }\n    successful_launches\n    status\n  }\n}\n\nquery LaunchByYear($year: String!) {\n  launches(find: { launch_year: $year }) {\n    mission_id\n    mission_name\n    launch_date_utc\n    rocket {\n      rocket_name\n    }\n  }\n}

\n\n\n\n

Let magic do it’s thing

\n\n\n\n

pnpm exec graphql-codegen

\n\n\n\n

This will look at all our custom queries and mutations and generate us a ready to consume SDK that is completely typed. Amazing!

\n\n\n\n

Leverage the new SDK

\n\n\n\n

// src/lib/gql/index.ts\n\nimport { GraphQLClient } from 'graphql-request'\nimport { getSdk } from './gen'\n\nconst client = new GraphQLClient('https://api.spacex.land/graphql/')\nexport const SDK = getSdk(client)

\n\n\n\n

import { SDK } from '$lib/gql'\n\nconst data = await SDK.LaunchByYear({ year: '2021' })

\n\n\n\n

You can also use the generated types to explicitly set them

\n\n\n\n

import { SDK } from '$lib/gql'\nimport type { GQLLaunchByYearQuery } from '$lib/gql/gen'\n\nconst data: GQLLaunchByYearQuery = await SDK.LaunchByYear({ year: '2021' })

\n\n\n\n

Every thing is typed now, I can’t pass a number to the year variable or use return data that does not exist. Typescript will error on me. This not only gives us autocompletion but also the safety of what we are doing.

\n\n\n\n

Configuration options

\n\n\n\n

I promised I would come back to it at some point.

\n\n\n\n

schema: ...\ngenerates:\n    ...\n    config:\n      maybeValue: \"T\"\n      typesPrefix: GQL\n      immutableTypes: true\n      useTypeImports: true\n      avoidOptionals: true

\n\n\n\n

There are many options for the generators, but I think these are quite sensible defaults.

\n\n\n\n

maybeValue is T | null as default, but since we only use our queries which are type safe we can just remove uncertainty and use the correct type straight away.

\n\n\n\n

avoidOptionals same thing as the maybeValue, just with prop:?. Don’t want that.

\n\n\n\n

typesPrefix is useful if you have some own type specifications that you don’t want to clash with. I like to prefix all my generated GraphQL stuff with GQL to keep it tidy.

\n\n\n\n

immutableTypes i prefer using an immutable type, with basically adds a readonly to every property. This way we are sure we are not editing data on the client.

\n\n\n\n

useTypeImports this uses import type whenever possible.

\n\n\n\n

Final thoughts

\n\n\n\n

I hope this made your GraphQL life a bit easier, it definitely did for me and it’s way more fun to consume GraphQL API this way. Also something worth mentioning is that you can use the @graphql-codegen/typescript-generic-sdk package instead of the @graphql-codegen/typescript-graphql-request if you want to do the network requests yourself. It’s easy to use but if you don’t really have a reason just stick with the graphql-request one I’d say.

\n","status":"publish","date":"2021-12-31T08:50:47","modified":"2021-12-31T09:23:03","tags":{"nodes":[{"id":"dGVybTo5Ng==","slug":"code-generation","name":"code-generation","count":1},{"id":"dGVybTo5NQ==","slug":"graphql","name":"graphql","count":1},{"id":"dGVybTo1Ng==","slug":"typescript","name":"typescript","count":2}]},"post":{"featured":{"srcSet":"https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-300x200.jpg 300w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-1024x683.jpg 1024w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-150x100.jpg 150w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-768x512.jpg 768w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-1536x1024.jpg 1536w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-2048x1365.jpg 2048w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-500x333.jpg 500w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-800x533.jpg 800w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-1200x800.jpg 1200w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-1500x1000.jpg 1500w, https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-2000x1333.jpg 2000w","altText":"","sourceUrl":"https://api.nicco.io/wp-content/uploads/2021/12/clayton-robbins-Ru09fQONJWo-unsplash-scaled.jpg"}}}]