chore(docs): Add GraphQL Typegen

[LekoArts]

Description

Adds documentation for GraphQL Typegen and adds an example using-graphql-typegen.

TODOs:

• ESLint plugin
• Schema customization
• Update examples

Documentation

• New page "GraphQL Typegen" - Rendered Version
• Linking to existing TypeScript page

Related Issues

#35420

[ch50091]

[Urigo]

Very excited about this @LekoArts !
Please let us know if we could help/support you somehow!

Do you think it would be helpful to mention somewhere that it uses the Codegen library under the hood or it just unnecessary for the users?

also I haven't got too deep to the implementation yet but did you get to look at TypedDocumentNode and the RFC from @cometkim ?
Would love to hear your thoughts on that approach

One last thing, here I would change from the unmaintained eslint-plugin-graphql to graphql-eslint

[LekoArts]

Hi @Urigo 👋

Please let us know if we could help/support you somehow!

I think what I'm still unsure about this how the VSCode GraphQL Plugin experience can come to other IDEs like emacs, vim, etc. -- how we'd document this. We generate a GraphQL config for this plugin so others that only implement a GraphQL language server should be able to reuse it? But I haven't found anything actionable yet via Google.

Do you think it would be helpful to mention somewhere that it uses the Codegen library under the hood or it just unnecessary for the users?

My stance is that as long as we don't expose public APIs that would interact with it it's not necessary to mention. I could write a conceptual guide about the feature (https://www.gatsbyjs.com/docs/conceptual/) which would be a good place to mention it. (As reference: https://www.gatsbyjs.com/docs/conceptual/image-plugin-architecture/)

also I haven't got too deep to the implementation yet but did you get to look at TypedDocumentNode and the RFC from @cometkim ?

We thought about this internally already prior to the RFC and long-term it's what we probably want to do. But it's not something we can do just now. When we revisit our query APIs we'll definitely keep that in mind. So this would be like a v2 of this typegen feature because it would be really neat to not have to import the types.

One last thing, here I would change from the unmaintained eslint-plugin-graphql to graphql-eslint

I intend to deprecate the plugin and link people to this now built-in feature, but good callout as I should add this to the docs that you can use it. Thanks!

[cometkim]

Inferred fields such as site metadata are nullable by default, and users may wonder if it is possible to make them non-nullable.

It would be nice to provide a simple example of adding a non-null assertion via schema customization and a link to the advanced guide to the schema customization.

exports.createSchemaCustomization = ({ actions }) => {
  actions.createTypes(`
    type Site {
      siteMetadata: SiteSiteMetadata! # This breaks build if siteMetadata is not provided
    }

    type SiteSiteMetadata {
      title: String! # This breaks build if title is not provided
  `);
};

[LekoArts]

@Urigo When trying to use the ESLint plugin I run into this:

Seems like dimaMachina/graphql-eslint#292 but I can't solve it. I added it here: cf3ccd8

[dimaMachina]

@LekoArts Hi there! I am the maintainer of graphql-eslint and I'm here to help you. It's strange but I don't have your error output. Instead, when I run yarn lint I have:

 dmytro@MBP-Dmytro  ~/Desktop/gatsby/examples/using-graphql-typegen   docs/typegen-two  yarn lint
yarn run v1.21.0
$ eslint . --ignore-path .gitignore --ext .ts,.tsx

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/404.tsx
  40:10  error  'process' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/index.tsx
  12:40  error  'Queries' is not defined  no-undef

✖ 2 problems (2 errors, 0 warnings)

error Command failed with exit code 1.

---

When I change your lint command to be eslint --ignore-path .gitignore . I receive another output:

 ✘ dmytro@MBP-Dmytro  ~/Desktop/gatsby/examples/using-graphql-typegen   docs/typegen-two  yarn lint
yarn run v1.21.0
$ eslint --ignore-path .gitignore .

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/.eslintrc.js
  1:1  error  'module' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/graphql.config.js
  1:1   error  'module' is not defined   no-undef
  1:18  error  'require' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/components/info.tsx
  0:0  error  Parsing error: [graphql-eslint] Cannot find module './.cache/typegen/graphql.config.json'
Require stack:
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/graphql.config.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/loaders.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/ExplorerBase.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/Explorer.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/graphql-config/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/@graphql-eslint/eslint-plugin/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/@eslint/eslintrc/dist/eslintrc.cjs

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/404.tsx
  40:10  error  'process' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/index.tsx
   0:0   error  Parsing error: [graphql-eslint] Cannot find module './.cache/typegen/graphql.config.json'
Require stack:
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/graphql.config.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/loaders.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/ExplorerBase.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/Explorer.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/cosmiconfig/dist/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/graphql-config/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/@graphql-eslint/eslint-plugin/index.js
- /Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/node_modules/@eslint/eslintrc/dist/eslintrc.cjs
  12:40  error  'Queries' is not defined                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             no-undef

✖ 7 problems (7 errors, 0 warnings)

---

So and finally to make it works I made yarn develop and in another terminal window yarn lint

 ✘ dmytro@MBP-Dmytro  ~/Desktop/gatsby/examples/using-graphql-typegen   docs/typegen-two ±  yarn lint
yarn run v1.21.0
$ eslint --ignore-path .gitignore .

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/.eslintrc.js
  1:1  error  'module' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/graphql.config.js
  1:1   error  'module' is not defined   no-undef
  1:18  error  'require' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/404.tsx
  40:10  error  'process' is not defined  no-undef

/Users/dimitri/Desktop/gatsby/examples/using-graphql-typegen/src/pages/index.tsx
  35:10  error  Field `site.id` must be selected when it's available on a type.
Include it in your selection set or add to used fragment `SiteInformation`  @graphql-eslint/require-id-when-available
  12:40  error  'Queries' is not defined                                                                                                                    no-undef

✖ 6 problems (6 errors, 0 warnings)

error Command failed with exit code 1.

[LekoArts]

Thanks @B2o5T 👍 I got it working now, too

[Khaledgarbaya]

LGTM, just 2 minor comments.
Did you consider adding a GIF or a video about how the feature is working? is this something we usually add our docs?

[Khaledgarbaya]

should this be

Suggested change

	This feature was added in `gatsby@4.15.0`.
	> This feature was added in `gatsby@4.15.0`.

[LekoArts]

We use the quote here and there to note this, but always under a heading. I felt that this was fine to add it as it's own sentence here.

But we don't have a style guide for this really

[Khaledgarbaya]

extra space to remove here

[LekoArts]

I intentionally indented it here as it refers to the code block above

[imjoshin]

Did you consider adding a GIF or a video about how the feature is working? is this something we usually add our docs?

PR looks good to me, but a GIF as @Khaledgarbaya suggested would be great for evangelizing the feature in our docs. Happy to ✅ if you feel otherwise. 😄

[LekoArts]

We'd want to have a video as you then can have subtitles, too, which makes it more accessible than a GIF.