See what's launched

The next gen Gatsby is here Performance, developer velocity, and scaling to meet Enterprise needs - See what’s launched

GraphQL Typegen

Examples

  • Using GraphQL Typegen

Introduction

If you’re already using Gatsby with TypeScript and manually typing the results of your queries, you’ll learn in this guide how Gatsby’s automatic GraphQL Typegen feature can make your life easier. By relying on the types that are generated by Gatsby itself and using autocompletion for GraphQL queries in your IDE you’ll be able to write GraphQL queries quicker and safer.

This feature was added in gatsby@4.15.0.

Prerequisites

Using the autogenerated Queries types

For this example to work you’ll have to have a title inside your siteMetadata (in gatsby-config).

  1. Start the development server with gatsby develop. Once the server is ready you should see a log message Generating GraphQL and TypeScript types at the bottom of your terminal.

  2. Gatsby created a type generation file which you should see at src/gatsby-types.d.ts. It contains the TypeScript types for your queries. Your tsconfig.json should include this file so that you can access the namespace Queries everywhere in your project.

  3. Create a new page at src/pages/typegen.tsx with the following contents:

    It is important that your query has a name (here: query TypegenPage {}) as otherwise the automatic type generation doesn’t work. We recommend naming the query the same as your React component and using PascalCase. You can enforce this requirement by using graphql-eslint.

  4. Access the Queries namespace and use the TypegenPageQuery type in your React component like so:

    When you type out the site title like this you should get TypeScript IntelliSense:

Configuration the gatsby-config option

Instead of setting a boolean value for the graphqlTypegen option in gatsby-config you can also set an object to configure it. See all details in the gatsby-config documentation.

If for example you use typesOutputPath to specify a different path, make sure to also update the "include" setting in your tsconfig.json to include the new path.

Non-Nullable types

As Gatsby infers all fields — unless an explicit schema by the user is provided — they are nullable by default. For GraphQL Typegen this means that fields are possibly null. You can see this in the example above where you had to type data.site?.siteMetadata?.title as both siteMetadata and title are nullable.

If you’re sure that siteMetadata.title is always available you can use Gatsby’s schema customization API to explicitly type your fields:

Read the Customizing the GraphQL schema guide to learn how to explicitly define types in your site or source plugin.

Tips

  • When adding a new key to your GraphQL query you’ll need to save the file before new TypeScript types are generated. The autogenerated files are only updated on file saves.
  • When using gatsby-plugin-image (and Image CDN) you’ll get the correct TypeScript types for gatsbyImageData and gatsbyImage automatically.
  • We recommend adding src/gatsby-types.d.ts to your .gitignore as it’s machine generated code and duplicated information that is already existent in e.g. your page queries.

Configuring the VSCode GraphQL plugin

  1. Install the GraphQL extension in your VSCode.

  2. Create a graphql.config.js at the root of your project with the following contents:

    The VSCode extension will pick up the graphql.config.js file and use the autogenerated file from Gatsby’s .cache directory. To learn more about graphql.config.js head to the GraphQL Config documentation.

  3. Restart VSCode so that the GraphQL extension takes effect.

  4. Start the development server with gatsby develop.

  5. Go to any of your queries, e.g. a page query inside src/pages and use Ctrl + Space (or use Shift + Space as an alternate keyboard shortcut) to get autocompletion like in GraphiQL.

Multiple GraphQL projects

If your repository has multiple GraphQL projects including Gatsby, you can configure it with the projects key:

Subdirectory

If your Gatsby project is in a subdirectory, e.g. site your config should look like this:

graphql-eslint

You can optionally use graphql-eslint to lint your GraphQL queries. It seamlessly integrates with the graphql.config.js file you created in the other step.

This guide assumes that you don’t have any existing ESLint configuration yet. You’ll need to adapt your configuration if you’re already using ESLint and refer to graphql-eslint’s documentation.

  1. Install dependencies

  2. Edit your package.json to add two scripts:

  3. Create a .eslintrc.js file to configure ESLint:

  4. Create a graphql.config.js at the root of your project with the following contents:

  5. Start the Gatsby development server with gatsby develop and check that .cache/typegen/graphql.config.json was created.

You can now use npm run lint and npm run lint:fix to check your GraphQL queries, e.g. if they are named.

Additional Resources

Edit this page on GitHub
© 2022 Gatsby, Inc.