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

> Learn to use Gatsby GraphQL typegen in TypeScript. Automatically generate TypeScript definitions for compile-time type safety and IDE autocompletion with gatsbyjs/gatsby.

- Repository: [Gatsby/gatsby](https://github.com/gatsbyjs/gatsby)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Enable `graphqlTypegen: true` in your [`gatsby-config.js`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/.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`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-config.js):

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

```

This minimal configuration enables type generation with sensible defaults, outputting definitions to [`src/gatsby-types.d.ts`](https://github.com/gatsbyjs/gatsby/blob/main/src/gatsby-types.d.ts).

### Advanced Options

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

```javascript
// 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`](https://github.com/gatsbyjs/gatsby/blob/main/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:

```tsx
// 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:

```tsx
// 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:

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

```

Gatsby automatically generates [`.cache/typegen/graphql.config.json`](https://github.com/gatsbyjs/gatsby/blob/main/.cache/typegen/graphql.config.json) during development. By re-exporting it in a root-level [`graphql.config.js`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-config.js).
- Generated types reside in [`src/gatsby-types.d.ts`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/.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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/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`](https://github.com/gatsbyjs/gatsby/blob/main/gatsby-node.ts) or plugin files. Add [`./gatsby-node.ts`](https://github.com/gatsbyjs/gatsby/blob/main/./gatsby-node.ts) or `./plugins/**/gatsby-node.ts` to the `documentSearchPaths` array in your `graphqlTypegen` configuration to generate types for Node API GraphQL operations.