[docs] Gatsby Internals docs should be updated (schema customization, Incremental Builds, v3)

[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 #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.

[tony]

My thread add #30070 is a duplicate of this, here's some more:

Request for examples of extensions

Some recommended topics to cover from Actions page#createTypes() and Schema customization

• @infer
• @dontInfer
• @dateformat
• @link
• @fileByRelativePath
• @proxy

Consider using @extensionName when referring to extensions

With @fileByRelativePath, right now we write:

fileByRelativePath is similar to link but will resolve relative paths when linking to File nodes, and proxy is helpful when dealing with data that contains field names with characters that are invalid in GraphQL.

If I see fileByRelativePath instead of @fileByRelativePath, it introduces ambiguity/mystery (in my opinion), is it an undocumented variable or undocumented method?

It may be clearer to always use @: @dateformat, @proxy and @link instead of dateformat, proxy and link.

Side idea: Example recipe showcasing complex, stable schema customization API

If I knew ahead of time the API was stable, I'd push for this and perhaps make one myself. I think it's hard to know if API/best practices will change in the coming 6-12 months or over years.

[tony]

Refresh documentation of @link's from / by?

I'm not sure if it's just me or not - but I still don't understand what from / by is for. I think that a visual representation or a section rewrite that shows what this looks like start to finish would be helpful.

To me this has a lot of logic/ambiguousness condensed in it:

You provide a @link directive on a field and Gatsby will internally
add a resolver that is quite similar to the one written manually above. If no
argument is provided, Gatsby will use the id field as the foreign-key,
otherwise the foreign-key has to be provided with the by argument. The
optional from argument allows getting the field on the current type which acts as the foreign-key to the field specified in by.
In other words, you link on from to by. This makes from especially helpful when adding a field for back-linking.

via https://github.com/gatsbyjs/gatsby/blob/63657680436f946c94589eb639fd692048c597bd/docs/docs/reference/graphql-data-layer/schema-customization.md#foreign-key-fields