Using types in your applications makes your code more secure, consistent, and robust. Types also allow you to detect and avoid mistakes as early as possible in the development process. This is particularly true for GraphQL types, which play a key role in your frontend application and enable you to avoid unexpected bugs and errors.

Writing types manually is time-consuming, cumbersome, and error-prone. Luckily, you can use a code generator to automatically generate TypeScript types from GraphQL queries.
Here, you will learn why adopting GraphQL types is so important, how to use graphql-codegen to generate TypeScript types from your .graphql files, why nullable fields may represent a problem, and how you can tackle this.

Why You Should Generate GraphQL Typescript Types

By default, GraphQL validates all requests and returns only schema-valid responses. However, your frontend application may not know what a schema-valid response looks like. This is especially true when using untyped languages, such as JavaScript. In this case, you might accidentally access nonexistent properties or forget to implement the right checks on null. This could lead to several errors in the application.

By using a typed language and adopting GraphQL types, you can avoid all this. To define types, you should use a GraphQL code generator. This is because it enables you to automatically generate the required TypeScript types from your GraphQL queries. Specifically, GraphQL code generators generate input and output types for GraphQL requests in your code. This means that by generating GraphQL TypeScript types, you can achieve extra validation for your GraphQL API calls. Also, accessing and using the results of your GraphQL requests will become easier and safer.

Generating Typescript Types From GraphQL With graphql-codegen

Let’s now learn how to automatically generate TypeScript types from your GraphQL queries with graphql-codegen.

Here, you will see an example based on a demo application that uses Next.js as the frontend technology and DatoCMS as the backend technology. Keep in mind that any TypeScript frontend technology and GraphQL-based backend technology will do.

Clone the GitHub repository supporting the article and run the demo application with the following commands:

git clone https://github.com/datocms/typescript-type-generation-graphql-example
cd typescript-type-generation-graphql-example
npm i
npm run dev

Now, follow this step-by-step tutorial and learn how to generate TypeScript GraphQL types with graphql-codegen.

Prerequisites

If you are a DatoCMS user, initialize a new project and create an Article model as follows:

First, you will need the following libraries:

graphql >= 16.6.0
graphql-request >= 5.0.0

You can install them with:

npm i graphql graphql-request

graphql-request is a lightweight and minimal library developed Prisma Labs that provides exactly what you need to perform GraphQL requests. Note that any other GraphQL client, such as Apollo GraphQL, will do.

Then, you will need the following libraries to make the code generation work:

@graphql-codegen/cli >= 2.12.0
@graphql-codegen/typed-document-node >= 2.3.3
@graphql-codegen/typescript >= 2.7.3
@graphql-codegen/typescript-operations >= 2.5.3
@graphql-typed-document-node/core >= 3.1.1

You can add all these libraries to your project’s dependencies with the following npm command:

npm i @graphql-codegen/cli @graphql-codegen/typed-document-node @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-typed-document-node/core

@graphql-typed-document-node/core is required to implement the TypedDocumentNode approach. Learn more here.

The first four libraries belong to the GraphQL codegen project. If you are not familiar with this project, GraphQL codegen gives you the ability to generate code from your GraphQL schema and operations.
This is all you need to generate TypeScript types from your GraphQL queries.

Let’s now see how to do it!

Setting Up graphql-codegen

To make graphql-codegen work, you need to define a GraphQL configuration file.

Create graphql.config.yml file in the root directory of your project and initialize it as follows:

1
schema:
2
  - https://graphql.datocms.com:
3
      headers:
4
        Authorization: "Bearer <YOUR_DATOCMS_API_TOKEN>"
5
documents: './graphql/**/*.graphql'
6
generates:
7
  graphql/generated.ts:
8
    plugins:
9
      - typescript
10
      - typescript-operations
11
      - typed-document-node
12
    config:
13
      strictScalars: true
14
      scalars:
15
        BooleanType: boolean
16
        CustomData: Record<string, unknown>
17
        Date: string
18
        DateTime: string
19
        FloatType: number
20
        IntType: number
21
        ItemId: string
22
        JsonField: unknown
23
        MetaTagAttributes: Record<string, string>
24
        UploadId: string
25

26
      # Optional, gives meta fields a leading underscore
27
      namingConvention:
28
        # enumValues: './pascalCaseWithUnderscores'

Note that the documents field must contain the path to the .graphql files storing your GraphQL queries. Also, change the schema field with the URL to your GraphQL schema. In this case, the GraphQL schema is retrieved directly from DatoCMS. Learn more on how to use GraphQL with DatoCMS.

If you are wondering what the scalars mentioned in the graphql.config.yml file are, take a look at this.

In a nutshell, DatoCMS uses some custom GraphQL scalar types. Therefore, you need to define them in your config file in order for the code generator to be able to transform the results retrieved from the DatoCMS Content Delivery API into TypeScript types.

Keep also in mind that the graphql.config.yml file can be used in the GraphQL extension for Visual Studio Code to get auto-completion and error checking directly in the IDE on GraphQL queries.

You are now ready to generate TypeScript types with graphql-codegen.

Optional: Leading underscores for meta fields

Optionally, you can use create the file ./pascalCaseWithUnderscores.js to give your generated enums for meta fields a leading underscore, like _CreatedAtAsc instead of CreatedAtAsc. That file should look like this:

1
/*
2
This the optional file /pascalCaseWithUnderscores.js
3

4
If you add this file to `namingConvention.enumValues` in your
5
`graphql.config.yml` file, it will add leading underscores where appropriate
6
*/
7

8
const { pascalCase } = require("change-case-all")
9

10
function pascalCaseWithUnderscores(str) {
11
  const result = pascalCase(str)
12

13
  if (!result) {
14
    return str
15
  }
16

17
  // if there is a leading underscore but it's not in the converted string, add it
18
  if (str.indexOf("_") === 0 && result.substring(0, 1) !== "_") {
19
    return `_${result}`
20
  }
21
  return result
22
}
23

24
module.exports = pascalCaseWithUnderscores

Generating TypeScript Types With graphql-codegen

First, add the following line to the scripts section of your package.json file:

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

This will launch the graphql-codegen type generation command as defined in the graphql.config.yml configuration file defined above. You can learn more about the arguments supported by this command here.

Now, launch the command below:

npm run generate-ts-types

Wait for the code generation process to end, and you should get:

✔ Parse Configuration
✔ Generate outputs

Now, enter the ./graphql directory, and you should be able to see a new generated.ts file. This contains all the TypeScript types generated by graphql-codegen.

In this simple DatoCMS example with only the Article model, generated.ts will look like as below:

1
import { TypedDocumentNode as DocumentNode } from "@graphql-typed-document-node/core"
2
export type Maybe<T> = T | null
3
export type InputMaybe<T> = Maybe<T>
4
export type Exact<T extends { [key: string]: unknown }> = { [K in keyof T]: T[K] }
5
export type MakeOptional<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]?: Maybe<T[SubKey]> }
6
export type MakeMaybe<T, K extends keyof T> = Omit<T, K> & { [SubKey in K]: Maybe<T[SubKey]> }
7
/** All built-in and custom scalars, mapped to their actual values */
8
export type Scalars = {
9
  ID: string
10
  String: string
11
  Boolean: boolean
12
  Int: number
13
  Float: number
14
  BooleanType: boolean
15
  CustomData: Record<string, unknown>
16
  DateTime: string
17
  FloatType: number
18
  IntType: number
19
  ItemId: string
20
  JsonField: unknown
21
  MetaTagAttributes: Record<string, string>
22
  UploadId: string
23
}
24

25
export type ArticleModelContentField = {
26
  __typename?: "ArticleModelContentField"
27
  blocks: Array<Scalars["String"]>
28
  links: Array<Scalars["String"]>
29
  value: Scalars["JsonField"]
30
}
31

32
export type ArticleModelFilter = {
33
  AND?: InputMaybe<Array<InputMaybe<ArticleModelFilter>>>
34
  OR?: InputMaybe<Array<InputMaybe<ArticleModelFilter>>>
35
  _createdAt?: InputMaybe<CreatedAtFilter>
36
  _firstPublishedAt?: InputMaybe<PublishedAtFilter>
37
  _isValid?: InputMaybe<BooleanFilter>
38
  _publicationScheduledAt?: InputMaybe<PublishedAtFilter>
39
  _publishedAt?: InputMaybe<PublishedAtFilter>
40
  _status?: InputMaybe<StatusFilter>
41
  _unpublishingScheduledAt?: InputMaybe<PublishedAtFilter>
42
  _updatedAt?: InputMaybe<UpdatedAtFilter>
43
  content?: InputMaybe<StructuredTextFilter>
44
  id?: InputMaybe<ItemIdFilter>
45
  image?: InputMaybe<FileFilter>
46
  slug?: InputMaybe<SlugFilter>
47
  title?: InputMaybe<StringFilter>
48
}
49

50
// Truncated for brevity...

You can have a look at the entire file here.

Now, let’s learn how to use these TypeScript types to perform GraphQL queries.

How To Use GraphQL API With Generated TypeScript Types

First, define a request.ts file in your lib folder as follows:

1
import { request as graphqlRequest, Variables } from "graphql-request"
2
import { RequestDocument } from "graphql-request/dist/types"
3
import { TypedDocumentNode } from "@graphql-typed-document-node/core"
4

5
export function request<TDocument = any>(
6
  document: RequestDocument | TypedDocumentNode<TDocument, Variables>,
7
  variables?: Variables,
8
) {
9
  return graphqlRequest<TDocument, Variables>("https://graphql.datocms.com/", document, variables, {
10
    Authorization: "xxx",
11
  })
12
}

Here, the graphql-request client library is used to define a request() function. This performs GraphQL requests based on the TypedDocumentNode approach and returns typed results.

Let’s now see request() in action:

1
import { GetStaticProps, NextPage } from "next"
2
import { Image as DatoImage } from "react-datocms"
3
import { HomeDocument, HomeQuery } from "../graphql/generated"
4
import { request } from "../lib/request"
5

6
const Home: NextPage<Props> = ({ result }) => {
7
  return (
8
    <ul>
9
      {result.allArticles.map((article) => (
10
        <li key={article.id}>
11
          {article.title} {article.image?.responsiveImage && <DatoImage data={article.image.responsiveImage} />}
12
        </li>
13
      ))}
14
    </ul>
15
  )
16
}
17

18
type Props = { result: HomeQuery }
19

20
export const getStaticProps: GetStaticProps<Props> = async (context) => {
21
  // retrieving the list of all articles
22
  const result = await request(HomeDocument)
23

24
  return {
25
    props: { result },
26
  }
27
}
28

29
export default Home

As you can see, you can perform a GraphQL request simply by using the TypeScript auto-generated types and objects. All you have to do is pass the right TypedDocumentNode to request() and it will return the expected typed result.

In detail, note that the result object returned by request() contains the allArticles field storing the list of Article objects retrieved by the GraphQL query defined in the ./graphql/home.graphql file below:

1
query Home {
2
  allArticles {
3
    id
4
    title
5
    _createdAt
6
    _publishedAt
7
    image {
8
      ...responsiveImage
9
    }
10
  }
11
}
12

13
fragment responsiveImage on FileFieldInterface {
14
  responsiveImage(imgixParams: { w: 100, h: 100, fit: crop }) {
15
    alt
16
    aspectRatio
17
    base64
18
    bgColor
19
    height
20
    sizes
21
    src
22
    srcSet
23
    title
24
    webpSrcSet
25
    width
26
  }
27
}

If you are wondering what HomeDocument and HomeQuery look like, you can find their definition in your generated.ts file.

Also, note that the Home component uses the DatoCMS Next.js Image component. Learn more about what DatoCMS has to offer when it comes to handling images in Next.js.

Congrats! You just learned how to automatically generate TypeScript types and objects from your GraphQL queries and use them to effortlessly perform GraphQL requests!

Why Required Fields Are Nullable When Using a Headless CMS

Headless CMS solutions usually allow you to define data models and populate entities accordingly. A data model is composed of several fields, each of which can be marked as required. When a field is considered required, it should always have a value. However, read carefully the following example and consider having a look at this thread.

Let’s suppose you have an Article model defined as seen earlier. You have already created several article records, and you want to extend the Article model with a new subtitle required field.

Now, every time you create an article record, you will have to specify a subtitle. On the other hand, the subtitle field will be initialized as null on already existing records, despite the required validation.

Therefore, any required field may actually have a null value. For this reason, all required fields are nullable in the GraphQL schema. Keep in mind that this is not a DatoCMS behavior, but an approach followed by all major headless CMS solutions.

Consequently, when automatically generating the TypeScript types from your GraphQL schema, all required fields will be marked as nullable.

1
export type ArticleRecord = RecordInterface & {
2
  __typename?: 'ArticleRecord';
3
  _createdAt: Scalars['DateTime'];
4
  /** Editing URL */
5
  _editingUrl?: Maybe<Scalars['String']>;
6
  _firstPublishedAt?: Maybe<Scalars['DateTime']>;
7
  _isValid: Scalars['BooleanType'];
8
  _modelApiKey: Scalars['String'];
9
  _publicationScheduledAt?: Maybe<Scalars['DateTime']>;
10
  _publishedAt?: Maybe<Scalars['DateTime']>;
11
  /** Generates SEO and Social card meta tags to be used in your frontend */
12
  _seoMetaTags: Array<Tag>;
13
  _status: ItemStatus;
14
  _unpublishingScheduledAt?: Maybe<Scalars['DateTime']>;
15
  _updatedAt: Scalars['DateTime'];
16
  content?: Maybe<ArticleModelContentField>;
17
  id: Scalars['ItemId'];
18
  image?: Maybe<FileField>;
19
  slug?: Maybe<Scalars['String']>;
20
  subtitle?: Maybe<Scalars['String']>;
21
  title?: Maybe<Scalars['String']>;
22
};

This is the auto-generated ArticleRecord TypeScript type. Notice that slug, subtitle, and title are all nullable, even if they are all marked as required.

This means that you always have to use the optional chaining operator, even if subtitle is required.

// subtitle may be null despite the required validation
article.subtitle?.toUpperCase()

Keep in mind that you have to use the optional chaining operator or define null checks on subtitle on all record entities, even though it may not be null on any record.

Note that DatoCMS would also mark article records with a null value for required fields as invalid through a false value on the is_valid attribute.

Filling your code with potentially unnecessary null checks is not elegant and makes your code dirtier, harder to read and maintain.

Fortunately, DatoCMS has a solution!

How To Avoid Nullable Types on Required Field in DatoCMS

DatoCMS allows you to globally exclude invalid records without always specifying an _isValid filter in your queries. You can achieve this by setting the following header:

X-Exclude-Invalid: true

This enables the so-called strict-mode for non-nullable GraphQL types. In detail, when this mode is enabled, any field marked as required will be associated with a non-nullable GraphQL type. Learn more about the DatoCMS Strict Mode for GraphQL.

Now, let’s see how to use this special header.

Update your graphql.config.yml file as follows:

schema:
  - https://graphql.datocms.com:
      headers:
        Authorization: "<YOUR_DATOCMS_API_TOKEN>"
        X-Exclude-Invalid: true

# omitted for brevity...

And your request.ts file as below:

1
import { request as graphqlRequest, Variables } from "graphql-request"
2
import { RequestDocument } from "graphql-request/dist/types"
3
import { TypedDocumentNode } from "@graphql-typed-document-node/core"
4

5
export function request<TDocument = any, TVariables = Record<string, any>>(
6
  document: RequestDocument | TypedDocumentNode<TDocument, Variables>,
7
  variables?: Variables,
8
) {
9
  return graphqlRequest<TDocument, Variables>("https://graphql.datocms.com/", document, variables, {
10
    Authorization: "<YOUR_DATOCMS_API_TOKEN>",
11
    "X-Exclude-Invalid": "true",
12
  })
13
}

Now, relaunch the code generation command:

npm run generate-ts-types

And generated.ts will contain the following type:

1
export type ArticleRecord = RecordInterface & {
2
  __typename?: "ArticleRecord"
3
  _createdAt: Scalars["DateTime"]
4
  /** Editing URL */
5
  _editingUrl?: Maybe<Scalars["String"]>
6
  _firstPublishedAt?: Maybe<Scalars["DateTime"]>
7
  _isValid: Scalars["BooleanType"]
8
  _modelApiKey: Scalars["String"]
9
  _publicationScheduledAt?: Maybe<Scalars["DateTime"]>
10
  _publishedAt?: Maybe<Scalars["DateTime"]>
11
  /** Generates SEO and Social card meta tags to be used in your frontend */
12
  _seoMetaTags: Array<Tag>
13
  _status: ItemStatus
14
  _unpublishingScheduledAt?: Maybe<Scalars["DateTime"]>
15
  _updatedAt: Scalars["DateTime"]
16
  content: ArticleModelContentField
17
  id: Scalars["ItemId"]
18
  image?: Maybe<FileField>
19
  slug: Scalars["String"]
20
  subtitle: Scalars["String"]
21
  title: Scalars["String"]
22
}

Now, slug, subtitle, and title in the ArticleRecord type are non-nullable as expected.

Et voilà! You no longer have to use unnecessary null checks in your TypeScript codebase.

Conclusion

In this article, you learned why you need GraphQL TypeScript types and how to automatically generate them from your GraphQL queries. This can be easily achieved with a GraphQL code generator. In detail, here you learned how to generate TypeScript types from GraphQL with graphql-codegen.

However, keep in mind that code generation comes with some challenges. This is particularly true when the GraphQL schema is defined through a headless CMS. In fact, required fields are generally marked as null.

Here, you learned how you can avoid this with DatoCMS, the powerful, fully-featured, easy-to-use headless CMS for developers and marketers.

Thanks for reading! We hope that you found this article helpful. Feel free to reach out to us on Twitter with any questions, comments, or suggestions.

TypeScript graphql

How To Generate TypeScript Types From GraphQL