Gatsby: [docs] Gatsby Internals docs should be updated for Schema Customization

[stefanprobst]

The "Gatsby Internals" ("Behind the scenes") docs for schema generation are out of date as they still refer to the pre-Schema Customization codebase.

[k-conway]

I'm interested in taking this one but was wondering if you could point me at a PR that fixes a similar issue for my reference.

Thanks!

[stefanprobst]

@k-conway This is great - and sorry for the very late reply!

Our schema generation code changed quite dramatically in version 2.2, so big chunks of that would have to be rewritten. I cannot point to an example PR, but my understanding is that the "Behind the scenes"/"Gatsby internals" docs should be like a narrated code walk-through.

The entry point in the schema build step is here, and a good overview of the steps involved are here and here.

• addTypes: adds explicitly defined type definitions from the createTypes action to the type registry
• addInferredTypes: use type inference to determine types for fields not explicitly defined
• addSetFieldsOnGraphQLNodeTypeFields: handle fields added by (legacy) setFieldsOnGraphQLNodeType API
• processTypeComposer: processes all types we have in the type registry. This involves:
  
  
  
  • processFieldExtensions: process custom field extensions defined by the createFieldExtension action, as well as built-in extensions like dateformat and link
  
  
  • for every type that implements the Node interface (i.e. types with unique ids created by source/transformer plugins):
    
    
    
    
    
    • addNodeInterfaceFields: add id, parent, children and internal fields to the type
    
    
    
    • addResolvers: derive input types for filter and sort, and produce output types for distinct and group fields, as well as pagination info
    
    
    
    • addConvenienceChildrenFields: add child/children fields like childImageSharp
    
    
    
    • addTypeToRootQuery: add the final fieldconfigs to the root Query type
    
    
    
  
  
• addThirdPartySchemas: add additional types from third-party schemas (i.e. added by gatsby-source-graphql) to the schema
• addCustomResolveFunctions: finally, process schema modifications from the createResolvers API

Don't hesitate to ask if anything is unclear!

[tbrannam]

Would be great to cover how to create directives for non-fields (createFieldExtension only covers FIELD_DEFINITIONS).
Is there an equivalent of createFieldExtension for types? It seems that there isn't a way to add a directive to non-fields? Looking for a way to add a directive that can be annotated at an Object level.

[stefanprobst]

@tbrannam what's the usecase for custom type extensions?

[tbrannam]

I may have the name of what I'm looking for wrong.

In this particular use case I am working to add additional metadata which would be processed by an Apollo-Link (by modifying the graphql context for the query) The implementation of the link would modify some headers which are required to modify some HTTP headers for a few specific Graphql queries (Localization related).

Originally I thought that I could somehow reach into the the gatsby-source-graphql config and somehow cause the fetch implementation to read some dynamic value - but the async nature of the these made it a synchronization issue. In apollo-client hooks (useQuery) I think that you could add additional properties to the context at the call site - which doesn't appear to be possible with a raw graphql call. I could see this as also being useful for call-site specific authorization as well.

query ($locales: string!) {
    pages @customlocalehttpheader($locales) {
      title
    }
}

Generally one could set the custom headers in the source config, but there are a couple of edge cases where the header needs to be modified.

[stefanprobst]

@tbrannam thanks for the writeup! interestingly, there has been another request today for custom type extensions, should we move the discussion there to discuss how an api for a createTypeExtension action should look like? See #18810

[alliestehney]

@stefanprobst is this still an open issue? If so, I came across this issue when reading the documentation on StaticQuery components and opened a small PR to include a mention of the new useStaticQuery hook.

[marcysutton]

Hi @alliestehney, yep it's still open! There is also https://github.com/gatsbyjs/gatsby/issues/18280 which needs some attention. We would welcome any contributions on this!

[muescha]

Overview

this pages need an update and are linked to this issue:

GraphQL Schema

• https://www.gatsbyjs.org/docs/schema-generation/
• https://www.gatsbyjs.org/docs/schema-gql-type/
• https://www.gatsbyjs.org/docs/schema-sift/
• https://www.gatsbyjs.org/docs/schema-input-gql/
• https://www.gatsbyjs.org/docs/schema-connections/

Internal

• https://www.gatsbyjs.org/docs/gatsby-internals.md
• https://www.gatsbyjs.org/docs/internal-data-bridge/
• https://www.gatsbyjs.org/docs/gatsby-internals-terminology.md
• https://www.gatsbyjs.org/docs/write-pages/

Node

• https://www.gatsbyjs.org/docs/page-node-dependencies/
• https://www.gatsbyjs.org/docs/node-tracking/

Query

• https://www.gatsbyjs.org/docs/query-behind-the-scenes/
• https://www.gatsbyjs.org/docs/query-extraction/
• https://www.gatsbyjs.org/docs/query-execution/

Other

• https://www.gatsbyjs.org/docs/how-plugins-apis-are-run.md
• https://www.gatsbyjs.org/docs/html-generation.md
• https://www.gatsbyjs.org/docs/production-app.md
• https://www.gatsbyjs.org/docs/resource-handling-and-service-workers.md

[aaronadamsCA]

For anyone like me who is looking at this now and wants to see the code @stefanprobst's was referencing in his comment, here are links to the schema files as they existed at the time of the comment:

The entry point in the schema build step is here, and a good overview of the steps involved are here and here.