How to Use Gatsby GraphQL Typegen in TypeScript Projects: A Complete Guide

Enable graphqlTypegen: true in your gatsby-config.js to automatically generate TypeScript definitions for all GraphQL operations, providing compile-time type safety and IDE autocompletion without runtime overhead.

Gatsby's GraphQL Typegen feature bridges the gap between GraphQL queries and TypeScript by auto-generating type definitions based on your actual schema. According to the gatsbyjs/gatsby source code, this tool scans your project for GraphQL literals and produces a declaration file that makes your query data fully typed throughout your application.

What Is Gatsby GraphQL Typegen?

GraphQL Typegen is a build-time service that analyzes GraphQL operations in your Gatsby project and generates corresponding TypeScript interfaces. Located in packages/gatsby/src/services/graphql-typegen.ts, the service orchestrates the generation process by collecting documents, stabilizing the schema, and invoking the codegen utilities.

The core generation logic resides in packages/gatsby/src/utils/graphql-typegen/ts-codegen.ts, which uses @graphql-codegen/core with three specific plugins: add (for file headers), typescript (for base schema types), and typescript-operations (for query-specific types). The output is wrapped in a declare namespace Queries block and written to src/gatsby-types.d.ts by default.

Why Enable GraphQL Typegen for TypeScript Projects?

Enabling GraphQL Typegen provides immediate development advantages with zero runtime cost:

• Strongly-typed GraphQL data: The generated Queries namespace contains specific types for every named operation (e.g., Queries.TypegenPageQuery), eliminating manual type definitions and preventing field name mismatches at compile time.

• IDE autocompletion: Because types are generated into your project source, editors like VS Code and WebStorm provide IntelliSense for query fields and fragment spreads directly in your TSX files.

• Zero runtime overhead: Type generation occurs only during gatsby develop or build processes. The output consists of plain .d.ts declaration files—no extra JavaScript ships to the browser.

• Fragment type safety: Each GraphQL fragment generates its own TypeScript type (e.g., SiteInformationFragment), allowing you to type component props that consume specific fragment data.

• Automatic schema synchronization: When your Gatsby schema evolves, running the development server regenerates types automatically, catching breaking changes during compilation rather than at runtime.

How to Enable and Configure GraphQL Typegen

Basic Configuration

Add the graphqlTypegen flag to your gatsby-config.js:

// gatsby-config.js
module.exports = {
  graphqlTypegen: true,
}

This minimal configuration enables type generation with sensible defaults, outputting definitions to src/gatsby-types.d.ts.

Advanced Options

For granular control, pass a configuration object instead of a boolean:

// gatsby-config.js
module.exports = {
  graphqlTypegen: {
    typesOutputPath: `src/gatsby-types.d.ts`,
    documentSearchPaths: [
      `./src/**/*.tsx`,
      `./gatsby-node.ts`,
      `./plugins/**/gatsby-node.ts`,
    ],
  },
}

The documentSearchPaths array specifies where Gatsby looks for GraphQL literals. By default, the system scans page components and static queries, but you can extend this to include gatsby-node.ts files or plugin code. The typesOutputPath determines where the Queries namespace declaration file is written.

Using Generated Types in Your Code

Typing Page Components

Import PageProps from gatsby and pass the generated query type as a generic parameter:

// src/pages/typegen.tsx
import * as React from "react"
import { graphql, PageProps } from "gatsby"

type Props = PageProps<Queries.TypegenPageQuery>

const TypegenPage: React.FC<Props> = ({ data }) => (
  <main>
    <h1>{data.site?.siteMetadata?.title}</h1>
  </main>
)

export const query = graphql`
  query TypegenPage {
    site {
      siteMetadata {
        title
      }
    }
  }
`

export default TypegenPage

The Queries.TypegenPageQuery type is automatically generated based on the query name. This provides full type safety for data.site and its nested properties.

Typing GraphQL Fragments

Fragments generate reusable types that you can apply to component props:

// src/components/info.tsx
import * as React from "react"
import { Queries } from "../../gatsby-types"

type Props = {
  buildTime?: Queries.SiteInformationFragment["buildTime"]
}

export const Info: React.FC<Props> = ({ buildTime }) => (
  <p>Build time: {buildTime}</p>
)

export const query = graphql`
  fragment SiteInformation on Site {
    buildTime
  }
`

Using Queries.SiteInformationFragment ensures your component only accesses fields explicitly defined in the fragment, preventing runtime errors when the parent query changes.

VS Code Integration

For enhanced IDE support, configure the GraphQL VS Code extension to recognize your Gatsby schema:

// graphql.config.js (project root)
module.exports = require("./.cache/typegen/graphql.config.json")

Gatsby automatically generates .cache/typegen/graphql.config.json during development. By re-exporting it in a root-level graphql.config.js, you enable field-level autocomplete, validation, and documentation hover tips directly inside your TSX files without additional configuration.

Summary

• Gatsby GraphQL Typegen automatically generates TypeScript definitions from your GraphQL queries, fragments, and schema during the build process.
• Enable it by setting graphqlTypegen: true (or a configuration object) in gatsby-config.js.
• Generated types reside in src/gatsby-types.d.ts within the Queries namespace, providing zero-runtime-cost type safety.
• Use PageProps<Queries.YourQueryName> for page components and Queries.YourFragmentName for fragment-based component props.
• The system scans documents using @graphql-tools/code-file-loader and stabilizes schemas for deterministic output via stabilizeSchema in packages/gatsby/src/utils/graphql-typegen/utils.ts.

Frequently Asked Questions

Does GraphQL Typegen affect runtime performance?

No. Type generation occurs exclusively during the build phase (gatsby develop or gatsby build) and produces only TypeScript declaration files (.d.ts). No additional JavaScript is bundled or executed in the browser, resulting in zero runtime overhead.

Where are the generated types stored?

By default, Gatsby writes the generated types to src/gatsby-types.d.ts in your project root. You can customize this path using the typesOutputPath option in the graphqlTypegen configuration object in gatsby-config.js.

Can I customize the output path for generated types?

Yes. Instead of passing a boolean to graphqlTypegen, provide a configuration object with the typesOutputPath property. For example: graphqlTypegen: { typesOutputPath: 'types/gatsby-types.d.ts' }. You can also specify custom documentSearchPaths to control which files are scanned for GraphQL literals.

Does GraphQL Typegen work with gatsby-node.ts?

Yes. By default, Gatsby scans page components and static queries, but you can extend the search paths to include gatsby-node.ts or plugin files. Add ./gatsby-node.ts or ./plugins/**/gatsby-node.ts to the documentSearchPaths array in your graphqlTypegen configuration to generate types for Node API GraphQL operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}