GraphQL Typegen

[LekoArts]

A built-in way for automatic TypeScript type generation and better GraphQL IntelliSense

Summary

GraphQL and TypeScript is a match made in heaven. When writing GraphQL queries in Gatsby, you’d also want exact TypeScript types for the respective return values to have type-safety and IntelliSense in your IDE. However, right now you manually have to create these TypeScript types or use a third-party plugin like gatsby-plugin-typegen.
By working together with the maintainer of gatsby-plugin-typegen we want to bring most of its functionality into the core of Gatsby (and improve the reliability, performance, and feature set). You’ll get automatic TypeScript type generation for your queries and in supported IDEs (VSCode) you’ll get enhanced IntelliSense for GraphQL queries.
Please see the “Questions for You” section and help us shape this feature. Thanks!

You can follow this milestone for updates on the progress.

Try it out

You can follow this guide: https://www.gatsbyjs.com/docs/how-to/local-development/graphql-typegen/

Then you can run gatsby develop and files will be created inside .cache/typegen. You can reference .cache/typegen/graphql.config.json inside a graphql.config.js at the root of your site to configure the GraphQL language server/VSCode extension.

Then inside your pages you can access the global namespace Queries to get your type information. Make sure that your queries have a name!

This project shows all this: https://github.com/gatsbyjs/gatsby/tree/master/examples/using-graphql-typegen

Basic Example

You can watch a short GIF here: https://www.gatsbyjs.com/docs/reference/release-notes/v4.14/#experimental-graphql-typegen

Note: https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql needs to be installed to have it working exactly as shown in the video. Some of this extension’s functionality is based on the GraphQL language server which is also available to other IDEs than VSCode.

Motivation

• Users must manually define types within pages/components/gatsby-node which is error prone, tedious, and sometimes difficult to do. Or they have to rely on third party plugins.
• Automatic TypeScript type generation has become a norm in the GraphQL + TypeScript space (e.g. Prisma, Apollo)
• The ecosystem around it (e.g. with VSCode extensions) is strong
• Autocompletion for data inside the page is less error prone
• (With VSCode Extension) Autocompletion inside GraphQL queries gives faster feedback loop and is less prone to errors

Detailed Design

The plugin’s code is on GitHub.

It will be (partially) incorporated into Gatsby’s core which brings some additional benefits:

• No private, internal APIs are used in the plugin that could break
• Gatsby can do some extra work to persist its schema and fragments by default
• Incorporate features from https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-graphql-config into this initiative

This is (on a high-level) what the plugin currently does and how it’ll roughly work also once it’s in Gatsby itself:

• Use graphql-codegen to convert GraphQL schema to TypeScript types. While doing that it makes the schema “stable”, as in removing things like dev-only properties, unnamed queries etc. It also sorts the schema lexicographically.
• Persist the schema, fragments from plugins etc. to files so that the GraphQL VSCode plugin can pick it up for its configuration
• Declare the types in a way that you can easily use them (currently a global namespace is used)
• Make it easy to use the VSCode GraphQL plugin
• Listen to your edits in files to automatically update TypeScript types, while being fast and reliable

Things we’d want to change when bringing it into Gatsby:

• Remove support for Flow
• Smaller API/options surface or smarter defaults
• Move the generation to a later stage of the develop/build process to keep it speedy
• Make GatsbyTypes less verbose, remove internal types
• Stretch goal: Support for workspaces/themes
• Change the name from GatsbyTypes to something like import type { Queries } from “gatsby” (or use a different way of surfacing the types, it’s something we’ll explore)

Drawbacks

• This adds additional dependencies to Gatsby
• Users will have to name their GraphQL queries for this to work. We need to update our documentation to account for this requirement
• Additional features besides TypeScript generation are working the best in VSCode, for other IDEs users will need to install the GraphQL language server

Alternatives

• Keep the feature in the plugin as-is

Adoption Strategy

A canary will be available for usage behind a feature flag. In the alpha and beta stage it’ll be in stable version of Gatsby but behind a feature flag (we might automatically opt-in people to see behavior/adoption on non-TS/TS sites).
Once GA it’ll be available without a feature flag.

How we teach this

• Add a new GraphQL Typegen documentation page and link to it also from the TypeScript doc page
• Update documentation to include names for queries
• Teach how to use VSCode extension and GraphQL language server in other IDEs
• Videos!

Questions for You

• Would you want to have the automatically generated types and GraphQL schema inside your source folder so that you can commit it to source control? Or should it stay hidden inside .cache?
• What are your rebuild times when you make changes to your files? You can get this information by running Gatsby with gatsby develop --verbose.
• Any other features we missed?

[axe312ger]

• Would you want to have the automatically generated types and GraphQL schema inside your source folder so that you can commit it to source control? Or should it stay hidden inside .cache?

I am playing around with GraphQL-codegen for a while and have been committing the generated files. Have to say they bloat my commits and give no real further use besides that others don't have to generate them. But now they can forget to generate them and this can cause confusion. Plus the source of truth for this information is already in other files, so IMHO:

No need to have them outside of .cache

• Do you need this generation during gatsby build or is gatsby develop enough?

Well, good question. On build it would probably slow down build times. But if we skip it there, we might have some people slipping through and using "old types".

For sure it should generate types when the cache is flushed from dependency updates and so on.

BUT I'd say thats okay, very most will develp with gatsby develop. We could provide a gatsby typegen script which would allow others to regerenate the types without touching `gatsby develop

Any other features we missed?

• maybe warn users with unnamed queries that they should name them?

[fafnirical]

I would love to have a gatsby typegen script to allow type-checking (tsc --noEmit) to work in environments where it wouldn't make sense to run gatsby develop first (such as in a CI pipeline)

[el7cosmos]

I would love to have a gatsby typegen script to allow type-checking (tsc --noEmit) to work in environments where it wouldn't make sense to run gatsby develop first (such as in a CI pipeline)

Would love this too, perhaps provide option to generate schema when building

[LekoArts]

@me4502 @fafnirical @el7cosmos I opened #36405 - feedback appreciated

[cjlint]

What was the reasoning for not generating .cache/typegen when generateOnBuild is enabled? Generating it would allow the graphql-eslint setup described in the docs https://www.gatsbyjs.com/docs/how-to/local-development/graphql-typegen/#graphql-eslint to also work in a CI environment, that would be beneficial right?

[wiwski]

@LekoArts I think @cjlint's question is relevant because it seems we can't use graphql-eslint in a CI environment.

EDIT : for a workaround, I am calling the typegen functions from onPostBuild : betagouv/euphrosyne-digilab@d8dc43e

[muescha]

Have to say they bloat my commits and give no real further use besides that others don't have to generate them.

i don't know how are the generated files look like.

but are the generated files useful to see the development changes better with just reading a commit? or there are just doubled the code changes which are also visible in other code places?

[LekoArts]

To give an example for this query:

  query IndexPage {
    allDataYaml {
      nodes {
        name
      }
    }
  }

The generated schema.graphql would contain (and a bunch of other related stuff):

type DataYaml implements Node {
  children: [Node!]!
  description: String
  id: ID!
  internal: Internal!
  name: String
  parent: Node
}

type DataYamlConnection {
  distinct(field: DataYamlFieldsEnum!): [String!]!
  edges: [DataYamlEdge!]!
  group(field: DataYamlFieldsEnum!, limit: Int, skip: Int): [DataYamlGroupConnection!]!
  max(field: DataYamlFieldsEnum!): Float
  min(field: DataYamlFieldsEnum!): Float
  nodes: [DataYaml!]!
  pageInfo: PageInfo!
  sum(field: DataYamlFieldsEnum!): Float
  totalCount: Int!
}

type DataYamlEdge {
  next: DataYaml
  node: DataYaml!
  previous: DataYaml
}

And TS types:

type IndexPageQuery = { readonly allDataYaml: { readonly nodes: ReadonlyArray<{ readonly name: string | undefined, readonly description: string | undefined }> } };

So I don't see any value in exposing this for all people as it's duplicated information.

[axe312ger]

Same, its duplicated information and worse to read as the original.

Lets keep the machine generate code for the machines :)

[LekoArts]

You can now use it with gatsby@next and a feature flag -- instructions are in the start post!

Please give it a try 🎉 You can also try this example project: https://github.com/LekoArts/graphql-typegen-testing

[cometkim]

Hi, I'm the author of gatsby-plugin-typegen.

I'm so excited to see this integrated into Gatsby.

Changes looks super great. Just a little suggestions.

1. Let the Maybe type be null, not undefined. It's one of the choices I regret the most. It allows a bit of syntax sugar in the project, but far from the type-safety.

2. I suggest designing the plugin interface to accommodate different opinions.

   Whether to commit the generated files or not, Or using Flow (or ReScript later) rather than TypeScript, these are all things I added and maintain options as I needed.

   It's nice to see Gatsby focusing to improve the TypeScript experience, but I think we need an escape hatch for users who have difference workflows.

   Expose some internals (e.g. SET_SCHEMA and SET_GRAPHQL_DEFINITIONS) used with this feature as official plugin APIs and provide feature toggle, allowing users to choose different workflows according to their needs.

3. It still need options.

   I understand you are concerned about complexity, but it really varies from project to project.

   • Putting generated files into node_modules is not compatible with projects using P'n'P .
   • Users may prefer the managing generated path over .cache, if they already have other code generators.
   • Users may want to commit the generated files. In CI, if user want to perform type checking before build, It will need a synchronized type declarations.
   • Users may prefer to review it themselve to be aware of changes.

Anyway, this is a nice topic to cover in Gatsby core.

I wrote an RFC to explain another approach that the user plugin cannot do.

[LekoArts]

Thanks for the comments so far!

1. I changed it to null again in feat(gatsby): Improvements to GraphQL TypeScript Generation #35581
2. We make the deliberate choice here to drop Flow here as TypeScript clearly won on popularity and usage. This will allow this feature to stay simple enough in its implementation. For the public API discussion I think this would need to warrant its own RFC. Do we event directly want to expose these two things or create a higher-level API? And a bunch of other open questions.
3. I don't think we'll go the Prisma route of putting stuff into node_modules for now, we'll revisit it when we'd want to pursue the idea you have in your RFC for typed query functions. For the other questions we'll see what feedback people give, so far there's not a lot of feedback yet so we'll wait the larger rollout and can change accordingly.

[LekoArts]

I merged #35581 - already available on gatsby@next. Functionality wise nothing should have changed (other than the Maybe<> type change). When you try it out, can you also check if your rebuild times when you make changes to your files increase?

I'll now focus on adding documentation: #35584

[bsgreenb]

Very happy this is getting integrated into Gatsby's core. Please make sure that whatever you setup works smoothly with Contentful.

Would be extra awesome if it could take a field being Required or not into account for nullability in TypeScript, that would be a great improvement over any of the current setups.

Looking forward to this

[LekoArts]

You can already try it out!

If a field is marked as required in the schema the type will reflect that by not having the null maybe type

[cometkim]

From typegen's experience, it raises awareness of the data layer, which is great!

We may need more guide on "why its type is nullable" and "how to fix it through schema customization" things 😄

And for source library authors, It will be also nice to have guide on how to tweak the schema so that users can take Typegen benefits.

[davidpaulsson]

This is gonna be so great! A question: Where would you put the files? I have a yarn workspace monorepo. The structure is somewhat like this.

/
-- /my-site-one
-- /my-site-two
-- /my-theme

I start my builds in my-site-one or my-site-two. They both use my-theme. Most deps are installed through the theme, and almost all code lives in the theme. Where do graphql.config.js go? In the root? In my-theme? In both sites’ folders?

[bsgreenb]

What I did for my monorepo is split off a package for the type schema (based on modifying generated types), generated types, and db migrations. It seems natural to split off these common db/type concerns in this way.

[davidpaulsson]

gatsbyImage comes through as Record<string, unknown>, shouldn't that be IGatsbyImageData? At least gatsby-plugin-image is complaining about it :) (Type 'Record<string, unknown>' is not assignable to type 'IGatsbyImageData') (but all in all, this is so cool!)

[LekoArts]

gatsbyImageData is a JSON GraphQL scalar so in https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/graphql-typegen/ts-codegen.ts#L31 it gets transformed to this record. I'll see if I can fix this, because yeah, you should get IGatsbyImageData really

[LekoArts]

Ah, I found dotansimha/graphql-code-generator#5748 - I'll check if we can fix this in the image plugin.

[LekoArts]

#35683 should fix it

[coderanger]

Is there any easy way to handle the case of of templated page queries where the returned object can't be null? As in I've got a page query:

export const pageQuery = graphql`
  query MyThingTemplate($name: String!) {
    myThing: myThingsJson(name: {eq: $name}) {

and the typegen semi-correctly points out that data.myThing could be null but in practical terms this isn't possible or should be a fatal error at the query level?

[LekoArts]

You'll want to use schema customization API to explicitly define your types/queries: https://www.gatsbyjs.com/docs/how-to/local-development/graphql-typegen/#non-nullable-types

[coderanger]

That works for the values in the query but not the top level of the query itself.

[fshowalter]

@coderanger You need to define the top-level query via createResolvers so you can denote the return type as non-null. See https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/#custom-query-fields

[LekoArts]

This feature is available in 4.15 now 🎉

https://www.gatsbyjs.com/docs/reference/release-notes/v4.15/#graphql-typegen

[Urigo]

Awesome work @LekoArts !!

let us know when it is announced on social media so we could spread the word!

[me4502]

Would it be possible to please get the outputted data in gatsby-types.d.ts sorted alphabetically or at least given a stable order? It seems that running gatsby develop can substantially modify the file as it moves things around, making it harder to keep in source control

[LekoArts]

This should already happen as stabilizeSchema is used inside the codegen portion:

gatsby/packages/gatsby/src/utils/graphql-typegen/utils.ts

Lines 10 to 15 in 93f7f89

	/**
	* Makes the schema deterministic by sorting it (so on new saves the whole file doesn't change, only the change that was made). It can be used for e.g. tests when two schema diffs should be compared.
	*/
	export function stabilizeSchema(schema: GraphQLSchema): GraphQLSchema {
	return lexicographicSortSchema(schema)
	}

Used in:

gatsby/packages/gatsby/src/utils/graphql-typegen/ts-codegen.ts

Line 128 in 93f7f89

schemaAst: stabilizeSchema(schema),

For what type of changes does the order change?

[wahidshafique]

I get the order changing as well; I guess I should just gitignore?

[cometkim]

Ah, right. we should stabilize not only schema but also the definitions from queries.

[LekoArts]

Ah, I'm missing cometkim/gatsby-plugin-typegen@9366cb2 - I'll add that to our code, too

[LekoArts]

Put up a PR: #35925

[nrandell]

I'm using this with tailwind and have found that it creates an infinite loop. Patching the ts-codegen file to put the gatsby-types.d.ts into the top directory appears to fix it. I'll get an issue created around this as well as I can reproduce it reasonably easily.

#35775

[openscript]

I'm trying to migrate to the built in solution for Graphql type generation from @graphql-codegen. How to deal with inline queries in such situations?

The situation looks like this:

import { CreatePagesArgs } from 'gatsby';
import { resolve } from 'path';

export async function CreateGenericPages({ actions, graphql }: CreatePagesArgs) {
  const { createPage } = actions;
  const allPages = await graphql<AllGenericPagesQuery>(`
    query AllGenericPages {
      allMdx(filter: { fields: { kind: { eq: "pages" } } }) {
        edges {
          node {
            id
            fields {
              path
              translations {
                locale
                path
              }
            }
          }
        }
      }
    }
  `);

  allPages.data?.allMdx.edges.forEach(p => {
    if (p.node.fields && p.node.fields.path) {
      createPage({
        component: resolve('./src/templates/GenericPage.tsx'),
        context: { id: p.node.id, translations: p.node.fields.translations },
        path: p.node.fields.path,
      });
    }
  });
}

How to I get the generated type for the AllGenericPages query?

[nrandell]

So do I. I had lots of issues with infinite loops and tailwindcss. This plugin is pretty much a direct copy of the core code but with some additional configuration that gets around the tailwindcss issues. I don't want to use it for very long though. Hopefully the core functionality will allow some configuration options soon!

[openscript]

Sounds great @nrandell! I'm also happy to create a PR with the ideas of your plugin, but only if somebody of the Gatsby team will look into it in less than a few months unlike the last time.

[nrandell]

I've created a feature request to allow options - see #35779

[LekoArts]

I'm already working on it :) https://github.com/gatsbyjs/gatsby/compare/typegen-options?expand=1
But ideally Gatsby would pick up the places for gatsby-node files by itself

[openscript]

@LekoArts Thank you so much! How can I support you with this?

[nrandell]

Is there any reason why the skipTypename value is set true? It's very useful to have the __typename field generated, especially when looking at unions.

I know they are generated in the query, but sometimes I will have a shared component where accessing the __typename field is simple.

Here's an example bit of code using it

function buildPageContent(
  contents: Queries.GraphCMS_PageContents,
  index: number
) {
  switch (contents.__typename) {
    case "GraphCMS_Item":
      return (
        <CMSItem
          key={contents.id}
          item={contents}
          index={index}
          simple={true}
        />
      );
    case "GraphCMS_Section":
      return <CMSSection key={contents.id} section={contents} />;
  }
  return <pre key={contents.id}>Type: {contents.__typename || ""}</pre>;
}

[nrandell]

I've been using this in a project all day and have switched from my original use to using the actual queries or fragments. It's taken a while to get used to the differences, but it produces a lot more correct code and removes the changes of errors. So I'm now happy with skipTypename set to true. It makes a lot of sense.

Here's the same function using the new code.

function buildPageContent(
  contents: Queries.PageFragment["contents"][0],
  index: number
) {
  switch (contents.__typename) {
    case "GraphCMS_Item":
      return (
        <CMSItem
          key={contents.id}
          item={contents}
          index={index}
          simple={true}
        />
      );
    case "GraphCMS_Section":
      return <CMSSection key={contents.id} section={contents} />;
  }
}

[cometkim]

There are many hidden context for selecting meaningful GCG config for Gatsby. Maybe we should leave some comments about it somewhere in the code.

[sandren]

I'm curious why the GraphQL typegen doesn't automatically infer whether or not a field is required (non-nullable) since everything in the data layer is already coming from Gatsby source plugins?

https://www.gatsbyjs.com/docs/how-to/local-development/graphql-typegen/#non-nullable-types

Lack of proper typing by default means you can't destructure data objects and have to do a lot of non-null assertions in all .tsx files with queries.

[cometkim]

@sandren It is the source plugin's job to determine "the field is non-null", and inferring schemas based on values is unstable because not all data sources have schema, so the nullability can be changed dynamically according to source changes, which means you should always re-run Typegen and type-checking in a CI environment, or your site will fails at runtime.

Instead, explicitly declare your schema and make it fails at the gatsby build.

[cometkim]

@nrandell Someday in the future, we will get the non-null assertion syntax (!) for this in the query :)

See twof/graphql-spec#1 (comment) and graphql/graphql-spec#867

[sandren]

@cometkim Fields set to required in Sanity are currently showing up as type x | null, but it sounds like further improvements to the gatsby-source-sanity plugin could resolve this? I know it can be done because Contentlayer produces proper types.

[cometkim]

Yes, it can If the plugin can figure out the schema from API or somewhat else.

In the case of gatsby-source-sanity, it seems the nullability is from Sanity API itself, not the Gatsby plugin which uses the SDL fetched from the remote GraphQL endpoint as-is.
https://github.com/sanity-io/gatsby-source-sanity/blob/e85707a5/src/util/remoteGraphQLSchema.ts#L53-L79

[sandren]

Yes, it can If the plugin can figure out the schema from API or somewhat else.

In the case of gatsby-source-sanity, it seems the nullability is from Sanity API itself, not the Gatsby plugin which uses the SDL fetched from the remote GraphQL endpoint as-is. https://github.com/sanity-io/gatsby-source-sanity/blob/e85707a5/src/util/remoteGraphQLSchema.ts#L53-L79

@cometkim Thank you for investigating this! I've reported the issue to Sanity. 🙂

[DJTB]

I'm not sure if I'm misunderstanding something, or if my setup is configured incorrectly.
I'm running into pains with TS maybe null types like @sandren above.

For the following:

  const result = useStaticQuery<Queries.FooterQuery>(graphql`
    query Footer {
      dataJson {
        footer {
          phone {
            text
          }
        }
      }
    }
  `);

If I hover those fields in the query I see String coming from the generated schema.graphql in .cache :

type DataJsonFooterPhone {
  text: String
}

However the type of the returned result of the query is the following:

type FooterQuery = { readonly dataJson: { readonly footer: { readonly phone: { readonly text: string | null } | null } | null } | null };

Is this the expected result without explicitly typing via the guide: https://www.gatsbyjs.com/docs/reference/graphql-data-layer/schema-customization/ ?

Is there any way to get the generated (I assume by the gatsby-transfomer-json plugin) explicit types instead?

[cometkim]

The Typegen plugin does not make any schema judgments on its own.

Is this the expected result without explicitly typing via the guide

That's the result expected by the source plugin, and the user should provide schema customization if it differs from the result you want.

Since the JSON file itself is not a schema and it doesn't guarantee input correctness, so commonly source plugins (that don't have schema metadata) guide the user to check nullability. Then write a custom transformer plugin to safely transform it into a derived node with a schema that the user wants.

1. Source Plugin(source with schema metadata) -> (SourceNode!) |<- Site(page queries) ✅
2. Source Plugin(source without schema) -> (SourceNode) -> Transformer Plugin(validate and filter source, derive node with schema) -> (ChildNode!) |<- Site(page queries) ✅ Type-safe
3. Source Plugin(source without schema) -> (SourceNode) |<- Site(page queries) + Strict null-checks ✅ Also type-safe, but runtime costs.

Consider making it stable. If you don't want that, just add a few lines of assertions to your gatsby-node.

exports.createSchemaCustomization = ({ actions }) => {
  actions.createTypes(`
    type DataJson {
      footer: DataJsonFooter!
    }
    type DataJsonFooter {
      phone: DataJsonFooterPhone!
    }
    type DataJsonFooterPhone {
      text: DataJsonFooterPhoneText!
    }
  `);
};

This code mark dataJson.footer.phone.text as non-null without any validation. But the site might fail silently if a field is missing from the source, at any time you didn't notice.

[DJTB]

Thanks for the timely, detailed reply. Much appreciated 🙇

[cometkim]

If you have other good examples for typegen + schema cusomization, please share!

This is an example PR for safely refactor blog content with custom schema
graphql/graphql.github.io#1125

[Notaduck]

I just upgraded to the latest version of Gatsby and enabled graphqlTypegen becauase why not?!
Now it just loops over this section over and over and clearing the cache doesn't seem to be helping here.

I don't know if the cause of this is that I gatsby-source-strapi or create a custom node type in gatsby-node.js?

warn Warning: Event "xstate.after(200)#waitingMachine.aggregatingFileChanges" was sent to stopped service "waitingMachine". This service has already reached its final state, and will not transition.
Event: {"type":"xstate.after(200)#waitingMachine.aggregatingFileChanges"}
success Re-building development bundle - 0.895s
success Writing page-data.json files to public directory - 0.008s - 0/60 7287.88/s
success onPreExtractQueries - 0.001s
success extract queries from components - 0.124s
success write out requires - 0.002s

[sandren]

@Notaduck Are you using Tailwind by chance? If so there is a solution to the infinite loop here. Just be sure to specify each of the directories that may contain class names (components, pages, etc) like in this example.

[Notaduck]

I am! I will try to take a look at it! Thanks.

:edit That did the trick!!! Thank you so much.

[kdichev]

Hi guys in my project I use static graphql sources plus client-side graphql source(live data with apollo). Before this new feature I have used gatsby graphql codegen plugin for the static and live queries. I use also hook generators for my live queries. My question is would it be possible "in the future" to use gatsby's internal codegen to generate my live hooks? I would really thing that this is a good idea but that's just me!

[cometkim]

Gatsby Typegen is using GCG internally to generates output, but it is specially configured only for Gatsby's data layer.

Since there is no context shared between Gatsby and any GraphQL client in the runtime, there is no benefit for that CGC instances to share config.

And unlike the CLI, Gatsby's built-in TypeGen is executed only when there is a change in the Gatsby data layer, not the source code.

You can still configure and use the CLI for your runtime context.

[bouiboui]

Hi 👋
I'm migrating an existing Gatsby site to TypeScript and I'm getting stuck.

If I import Queries.IndexPageQuery from TypeScript's global namespace, my IDE is happy but Gatsby is not:

Webstorm

Gatsby develop (Unhandled Runtime Error)

If I leave it out, Gatsby builds correctly but tsc --noEmit and my IDE are shouting at me:

tsc --noEmit (Cannot find name 'IndexPageQuery')

Webstorm

I don't understand how I am the only one reporting this.
Are 100% of Gatsby users using VSCode or am I doing something wrong? 😑

Here's my tsconfig file (taken from gatsby-minimal-starter-ts):

tsconfig.json

{
  "compilerOptions": {
    /* Language and Environment */
    "target": "esnext",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
    "lib": ["dom", "esnext"],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
    "jsx": "react",                                /* Specify what JSX code is generated. */

    /* Modules */
    "module": "esnext",                                /* Specify what module code is generated. */
    "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables `allowSyntheticDefaultImports` for type compatibility. */
    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */

    /* Type Checking */
    "strict": true,                                      /* Enable all strict type-checking options. */
    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
  },
  "include": ["./src/**/*", "./gatsby-node.ts", "./gatsby-config.ts", "./plugins/**/*"]
}

Thanks 🙏

[nrandell]

Just use PageProps<Queries.IndexPageQuery> and it should work

[bouiboui]

It does 😳

My mistake was typing PageProps<IndexPageQuery> and letting Webstorm suggest me the automatic import:

Well, that was quick and easy.
Thanks a lot @nrandell !

[aravifrog]

Looking for Gatsby + TypeScript HELP! I'm having a query like this and using Typegen. From this, how can I pick the type of videoContentReference alone? I have to pass the data from videoContentReference into another component. In general, from a query, can we get the type of a particular nested object alone?

Right now I'm doing something like this on the child component Interface:
data: DetailPageItemTypegen['allContentfulDetailPage']['edges'][0]['node']['videoContentReference'];

Not sure if is it the right way. Looking for some guidance.

Thanks for your time!

[cometkim]

That is the moment you need to use fragments

Let me introduce some pattern called "fragment colocation"

// In the page component
export const query = graphql`
# This generate `Queries.DetailPageQuery` type
query DetailPage($id: String) {
  contentfulDetailPage(id: { eq: $id }) {
    ...DetailPageInner_data
  }
}
`;

// In <DetailPageInner> component, you can still export graphql only for fragment definition.

// Let's use it to declare what data your component exactly need
type DetailPageInnerProps = {
  data: Queries.DetailPageInner_dataFragment,
};

export const fragments = graphql`
# This generate `Queries.DetailPageInner_dataFragment` type 
fragment DetailPageInner_data on ContentfulDetailPage {
  detailPageTitle
  pageUrl
  ...DetailPageReference_reference
}
`;

// Even in the nested component, ex) <DetailPageReference>
type DetailPageReferenceProps = {
  reference: Queries.DetailPageReference_referenceFragment,
};

export const fragments = graphql`
# This generate `Queries.DetailPageReference_referenceFragment` type 
fragment DetailPageReference_reference on ContentfulDetailPage {
  videoContentReference {
    videoTemplateType
  }
  videoUrl
  id
}
`;

This pattern is quite common in GraphQL clients like Relay

Dependencies declared as fragments can be safely passed to the child components because they are merged by the compiler and the actual data is always superset.

function DetailPage({ data }: PageProps<Queries.DetailPageQuery>) {
  return (
    {/* you can safely pass data here */}
    <DetailPageInner data={data} />
  );
};

function DetailPageInner({ data }: DetailPageInnerProps) {
  return (
    {/* also here */}
    <DetailPageReference reference={data} />
  );
}

// ... so on

[aravifrog]

@cometkim This is something really new to me. Thanks for taking the time and explaining it! Appreciate it!

[LekoArts]

It'll be in our docs soon :) #36386

[bsgreenb]

@LekoArts Can't wait to implement this on new project!

[natapg]

Hey everyone, maybe it's a stupid question, but the file is generated during the build? I tried yarn build and the file with the types is not generated, so I had to commit it to avoid problems with the tests during my CI

[el7cosmos]

Yes, it's not generated on build, and that's a NO in a CI environment, meanwhile, documentation recommends to ignore it

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.

@LekoArts can we get an option to generate it during build?

[LekoArts]

@natapg please see #35420 (reply in thread)

[kota65535]

Hi @LekoArts
I'm running Cypress test that runs gatsby develop. Because documentation recommends to ignore src/gatsby-types.d.ts, the cloned repository does not have src/gatsby-types.d.ts.

1. The first gatsby develop fails because GraphQL and TypeScript types are not generated like this

Generating development JavaScript bundle failed

ERROR in /Users/tozawa/SRE/Samples/sample-basic/sample-basic-front/src/hooks/useSiteMetadata/index.ts(28,15):
28:15 Cannot find namespace 'Queries'.
    26 | 
    27 | const useSiteMetadata = () => {
  > 28 |   const data: Queries.UseSiteMetadataQuery = useStaticQuery(query);
       |               ^
    29 | 
    30 |   const meta = data.site?.siteMetadata || ({} as Queries.SiteSiteMetadata);
    31 | 

File: src/hooks/useSiteMetadata/index.ts

2. Then the second gatsby develop runs successfully

Is this an expected behavior?

[kaushalyap]

@LekoArts can you please help me with this : https://stackoverflow.com/questions/74065597/warn-warning-event-xstate-after200waitingmachine-aggregatingfilechanges-wa?

Simply put: enabling graphql typegen get me into infinite build loop.