Produce type-safe GraphQL queries using TypeScript 💥
Tags: javascript, typescript, graphql, webdev
Published: 2023-01-12 16:06:04

## TL;DR

In this tutorial, you'll learn how to produce type-safe GraphQL queries using TypeScript using some great tools, techniques, and solutions.

## Intro
When you're building a company obsessed with making front-end teams' lives better, it's only natural to spend a lot of time thinking about front-end type things.

And that explains a lot about my team.

But we figured that instead of just daydreaming, we'd try to turn our random thought process into something more productive and useful for people like you. 😅

We were recently reflecting on how much front end developers love GQL. It also occurred to us that they also love TypeScript. 

**So... how amazing would it be if we could combine them?**

![Livecycle thinking](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wflcuc3icl7rvy2mlppt.gif)

As it turns out, there are a bunch of tools that can help developers produce type-safe GraphQL queries using TypeScript. In this article, we will explore the cream-of-the-crop tools, techniques, and solutions that can help create a great experience for developers.

## Livecycle - the best way for front end devs to collaborate & get PRs reviewed... fast.

[Now, just some quick background on who we are, so you'll understand why we're daydreaming about this kind of thing. 

Livecycle is a contextual collaboration tool for front-end development teams. We know how painful it is trying to get multiple stakeholders to review changes before they go live (unclear comments... context switches... different time zones... too many meetings... zero coordination... you know **exactly** what I'm talking about 🙄) so we built a solution. 

Our SDK turns any PR deploy preview environment into a collaborative playground where the team can leave visual review comments in context. By facilitating a contextual, async review we save frontend teams tons of time, money and headaches. (If your team is building a product together - [check out how Livecycle can help](https://www.sdk.livecycle.io/?utm_source=devto&utm_medium=post&utm_campaign=devtogqlts))]

And now back to our regular scheduled program... Buckle up. 

## Autocomplete for Writing Queries

Let's start by exploring some techniques for showing autocomplete types when writing queries. Autocomplete is a nice feature that allows developers to see the available schema options for fields, arguments, types, and variables as they write queries. It should work with .graphql files and ggl template strings as well.

![figure1](https://lh3.googleusercontent.com/NbSo13v-FAyHJdC88sZXaZXmPjU2tiXtSZZCdFJDWE-jX0z4BZZFSChDsQAQ_A5Gj7DaZGQlk4k_M-HfXK3zKtY1r-I1A6QhMTMj8pElTCN2r6VvdXyyzuXTl6SF4isZYDqnk8VD)

Fig 1: Autocomplete in Action

The editor that you use will determine the process of setting up autocomplete in TypeScript as well as the method of applying the correct configuration.

For example, say that you have a GraphQL endpoint in <http://localhost:10008/graphql> and you want to enable autocomplete for it. You need to introspect the schema and use it to fill the autocomplete options.

### Introspecting the Schema

You need to enable the editor to match the schema and show the allowed fields and types as you write. This is easy if you use Webstorm with the [GraphQL plugin](https://plugins.jetbrains.com/plugin/8097-graphql). Just click on the tab to configure the endpoint that you want to introspect, and it will generate a [graphql-config](https://graphql-config.com/introduction/) file that looks something like this:

![figure2](https://lh3.googleusercontent.com/FqzPrV_x3sqI_FNWBI92PxGAdnwEcMNLBQMwzAYWSHI2jEo904W86mFI-a3kYTaxllRHCIOmmLmHKKSHIi-FDLjKwhmLKQXqV13Mqfb2oqFoc7wvabHFV5oDryCJ950SkTvBV8aX)

Fig 2: The Webstorm GraphQL Plugin


```js
// ./graphql-config.json
{
  "name": "MyApp",
  "schemaPath": "schema.graphql",
  "extensions": {
    "endpoints": {
      "Default GraphQL Endpoint": {
        "url": "http://localhost:10008/graphql",
        "headers": {
          "user-agent": "JS GraphQL"
        },
        "introspect": true
      }
    }
  }
}
```

Once this step is finished, you will be able to use autocomplete when writing ggl and .graphql queries.

You can also do this using VSCode with the [VSCode GraphQL plugin](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql). You may want to download the schema file first:

```bash
npm i get-graphql-schema -g
get-graphql-schema http://localhost:10008/graphql > schema.graphql
```

Then, if you use the previous graphql-config.json file, everything should work as expected there as well.

## Generating Types Automatically from Gql/Graphql Files

Once you have the autocomplete feature enabled, you should use TypeScript to return valid types for the result data when you write ggl files.

In this case, you need to generate TypeScript types from the GraphQL schema so that you can use the TypeScript Language Server to autocomplete fields in code.

First, you use a tool called [@graphql-codegen](https://www.graphql-code-generator.com/) to perform the schema -> TypeScript types generation. Install the required dependencies like this:

```bash
npm i @graphql-codegen/introspection \
  @graphql-codegen/TypeScript @graphql-codegen/TypeScript-operations \
  @graphql-codegen/cli --save-dev
```

Then, create a codegen.yml file that contains the code generation configuration:

```yml
# ./codegen.yml
overwrite: true
schema: "http://localhost:10008/graphql"
documents: "pages/\*\*/\*.graphql"
generates:
  types/generated.d.ts:
    plugins:
      - typescript
      - typescript-operations
      - introspection
```

Just add the location of the schema endpoint, the documents to scan for queries, and the location of the generated files to this file.

For example, we have a posts.graphql file with the following contents:

```graphql
# ./posts.graphql
query GetPostList {
  posts {
    nodes {
      excerpt
      id
      databaseId
      title
      slug
    }
  }
}
```

Then, we add this task in package.json and run it:


```js
// package.json

"scripts": {

/*
...
*/

"generate": "graphql-codegen --config codegen.yml",

}
```

```bash
npm run generate
```

This will create ambient types in types/generated.d.ts. Now we can use them in queries:

```typescript
import postsQuery from "./posts.graphql"
import { GetPostListQuery } from "../types/generated"

const [response] = useQuery<GetPostListQuery>({ query: postsQuery })
```

Note: we're able to load .graphql files using import statements with the following webpack rule:

```javascript
{
      test: /\.(graphql|gql)$/,
      exclude: /node_modules/,
      loader: 'graphql-tag/loader',
 }
```

Now, the response data will be properly typechecked when you access the relevant fields even if you don’t type anything:

![figure3](https://lh4.googleusercontent.com/NhITY9UMB7ukN6iSUYFhO69y4V6nsk4wvN1cgwMhd8O94tSGx0VhhIJWPcbWqAOcdnpgR6a36nvE5gqMGye5-VNlP81s2qOOa9o5M3yEpMrkViiWqHR06XDMTuJnFLfiRKbhBUPY)

Fig 3: Using Generated Types in TypeScript

You can also watch the .graphql files and automatically generate the appropriate types without going back and running the same commands again by adding the -w flag. That way, the types will always be in sync as you update them:


```js
//package.json

"scripts": {

//…

"generate": "graphql-codegen --config codegen.yml -w,

}

```

## Better type inference using typed-document-node

The GraphQL Code Generator project offers a variety of plugins that make it possible to provide a better development experience with Typescript and GraphQL. One of those plugins is the [typed-document-node](https://www.graphql-code-generator.com/plugins/typed-document-node) which allows developers to avoid importing the .graphql file and instead use a generated Typescript type for the query result. As you type the result of the operation you just requested you get automatic type inference, auto-complete and type checking.

To use it first you need to install the plugin itself:

```bash
npm i @graphql-typed-document-node/core  \
  @graphql-codegen/typed-document-node --save-dev
```

Then include it in the codegen.yml file:

```yml
# ./codegen.yml

overwrite: true
schema: "http://localhost:10008/graphql"
documents: "pages/\*\*/*.graphql"
generates:
  types/generated.d.ts:
    plugins:
    - typescript
    - typescript-operations
    - typed-document-node
    - introspection
```

Now run the generate command again to create the new TypedDocumentNode which extends the [DocumentNode](https://github.com/graphql/graphql-js/blob/564757fb62bfd4e2472e6e7465971baad2371805/src/language/ast.ts#L342-L345) interface. This will update the types/generated.d.ts file that includes now the following types:

```typescript
export type GetPostListQueryVariables = Exact<{ [key: string]: never; }>;
export type GetPostListQuery = …
export const GetPostListDocument = …
```

Now instead of providing the generic type parameter in the query, you just use the GetPostListDocument constant and remove the .graphql import, which allows Typescript to infer the types of the result data. So we can change the index.tsx to be:

index.tsx

```tsx
import { GetPostListDocument } from "../types/generated.d";
…

const result = useQuery(GetPostListDocument);
```

You can query the response data which will infer the types for you as you type:

![figure4](https://lh4.googleusercontent.com/uj3vpWhALEkr4TSIBKarop0q8h5lOHJMwb87fPkDMV4aAFAYb1DFzXUV6rBaPOx9oYFg52AjQ5v4ogmo1_V4Ne6q6iZ95vDohW8rOOdfdrpTwN3Ea406QLmXjV9_tbGLD-j-PcFp)

Overall this plugin greatly improves the development experience when working with GraphQL queries.

## Data Fetching Libraries for Web and Node/Deno

Finally, let’s explore the best data fetching libraries for Web and Node/Deno. There are three main contenders:

### Graphql-Request

This is a minimalist GraphQL client, and it’s the simplest way to call the endpoint aside from calling it directly using fetch. You can use it to perform direct queries to the GraphQL endpoint without any advanced features like cache strategies or refetching. However, that does not stop you from leveraging the autocomplete and typed queries features:

```bash
npm i graphql-request --save
```

```tsx
// ./getPosts.tsx

import { gql } from "@apollo/client"
import { request } from "graphql-request"
import { GetPostListQuery } from "../types/generated"

export const getPosts = async () => {
  const data = await request<GetPostListQuery>(
    "http://localhost:10003",
    gql`
        query GetPostList {
            posts {
                nodes {
                    excerpt
                    id
                    databaseId
                    title
                    slug
                }
            }
        }
    `
  )

  return data?.posts?.nodes?.slice() ?? []
}
```

For example, you can use the request function to perform a direct query to the GraphQL endpoint and then pass on the generated GetPostListQuery type. While you are typing the query, you’ll see the autocomplete capability, and you can also see that the response data is typed correctly. Alternatively, if you do not want to pass on the endpoint every time, you can use the GraphQLClient class instead:

```tsx
import { GraphQLClient } from "graphql-request"
import { GetPostListQuery } from "../types/generated"

const client = new GraphQLClient("http://localhost:10003")

export const getPosts = async () => {
  const data = await client.request
}
```

### Apollo Client

This is one of the oldest and most feature-complete clients. It offers many useful production grade capabilities like cache strategies, refetching, and integrated states.

Getting started with Apollo Client is relatively simple. You just need to configure a client and pass it around the application:

```bash
npm install @apollo/client graphql
```

```typescript
// client.ts

import { ApolloClient, InMemoryCache } from "@apollo/client"

const client = new ApolloClient({
  uri: "http://localhost:10003/graphql",
  cache: new InMemoryCache(),
  connectToDevTools: true,
})
```

You want to specify the uri to connect to, the cache mechanism to use, and a flag to connect to the dev tools [plugin](https://chrome.google.com/webstore/detail/apollo-client-devtools/jdkknkkbebbapilgoeccciglkfbmbnfm). Then, provide the client with the query or mutation parameters to perform queries:

```tsx
// ./getPosts.tsx

import client from "./client"
import { gql } from "@apollo/client"
import { GetPostListQuery } from "../types/generated"

export const getPosts = async () => {
  const { data } = await client.query<GetPostListQuery>({
    query: gql`
          query GetPostList {
              posts {
                  nodes {
                      excerpt
                      id
                      databaseId
                      title
                      slug
                  }
              }
          }
      `,
  })

  return data?.posts?.nodes?.slice() ?? []
}
```

If you’re using React, we recommend that you connect the client with the associated provider, as follows:

```tsx
// ./index.tsx

import { ApolloProvider } from "@apollo/client"
import client from "./client"

const App = () => (
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>
)
```

Overall, Apollo is a stable and feature-complete client that will cater to all of your needs. It’s a good choice.

### Urql

This is a more modern client from Formidable Labs. It’s highly customizable and very flexible by default. Urql leverages the concept of [exchanges](https://formidable.com/open-source/urql/docs/architecture/), which are like middleware functions that enhance its functionality. It also comes with its own [dev tools](https://github.com/FormidableLabs/urql-devtools/) extension and offers many add-ons. You begin the setup process (which is very similar to those discussed above) as follows:

```
npm install --save @urql/core graphql
```

```typescript
// ./client.ts

import { createClient, defaultExchanges } from "urql"
import { devtoolsExchange } from "@urql/devtools"

const client = createClient({
  url: "http://localhost:10003/graphql",

  exchanges: [devtoolsExchange, ...defaultExchanges],
})
```


#### queries.gql

```graphql
# ./graphql/queries.gql

query GetPostList {
  posts {
    nodes {
      excerpt
      id
      databaseId
      title
      slug
    }
  }
}
```


You need to specify the url to connect to and the list of exchanges to use. Then, you can perform queries by calling the query method with the client and then converting it to a promise using the toPromise method:

```typescript
// ./index.ts

import client from "./client"
import { GetPostDocument } from "../types/generated"

async function getPosts() {
  const { data } = await client.query(GetPostDocument).toPromise()
  return data
}
```

Overall, Urql can be a good alternative to Apollo, as it is highly extensible and provides a good development experience.

In addition, if we're using React app, we can install the [@graphql-codegen/typescript-urql](https://www.graphql-code-generator.com/plugins/typescript-urql) plugin and generate [higher order components](https://reactjs.org/docs/higher-order-components.html) or hooks for easily consuming data from our GraphQL server.

## Bottom line & Next Steps with GraphQL and TypeScript

At the end of the day, we just want to make developers happy. So we genuinely hope that you enjoyed reading this article.

For further reading, you can explore more tools in the GraphQL ecosystem by looking through the [awesome-graphql](https://github.com/chentsulin/awesome-graphql) list. 

## Check us out!

If you found this article useful, then you're probably the kind of human who would appreciate the value Livecycle can bring to front end teams. 

I'd be thrilled if you [installed our SDK](https://www.sdk.livecycle.io/?utm_source=devto&utm_medium=post&utm_campaign=devtogqlts) on one of your projects and gave it a spin with your team. 🙏

<!--EndFragment-->