Skip to content

Commit

Permalink
chore(docs): Add fragments to GraphQL typegen (#36386)
Browse files Browse the repository at this point in the history
initial
  • Loading branch information
LekoArts authored Aug 15, 2022
1 parent c5ad03a commit 0744cfd
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 2 deletions.
48 changes: 48 additions & 0 deletions docs/docs/how-to/local-development/graphql-typegen.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,54 @@ export const createSchemaCustomization: GatsbyNode["createSchemaCustomization"]

Read the [Customizing the GraphQL schema guide](/docs/reference/graphql-data-layer/schema-customization/) to learn how to explicitly define types in your site or source plugin.

### GraphQL fragments

Fragments allow you to reuse parts of GraphQL queries throughout your site and collocate specific parts of a query to individual files. Learn more about it in the [Using GraphQL fragments guide](/docs/reference/graphql-data-layer/using-graphql-fragments/).

In the context of GraphQL Typegen fragments enable you to have individual TypeScript types for nested parts of your queries since each fragment will be its own TypeScript type. You then can use these types to e.g. type arguments of components consuming the GraphQL data.

Here's an example (also used in [using-graphql-typegen](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-graphql-typegen)) with a `Info` component that gets the `buildTime` as an argument. This `Info` component and its `SiteInformation` fragment is used in the `src/pages/index.tsx` file then:

```tsx:title=src/components/info.tsx
import * as React from "react"
import { graphql } from "gatsby"

// highlight-next-line
const Info = ({ buildTime }: { buildTime?: any }) => {
return (
<p>
Build time: {buildTime}
</p>
)
}

export default Info

// highlight-start
export const query = graphql`
fragment SiteInformation on Site {
buildTime
}
`
// highlight-end
```

```graphql:title=src/pages/index.tsx
# Rest of the page above...

query IndexPage {
site {
...SiteInformation
}
}
```

This way a `SiteInformationFragment` TypeScript type will be created that you can use in the `Info` component:

```tsx:title=src/components/info.tsx
const Info = ({ buildTime }: { buildTime?: Queries.SiteInformationFragment["buildTime"] }) => {}
```

### Tips

- When adding a new key to your GraphQL query you'll need to save the file before new TypeScript types are generated. The autogenerated files are only updated on file saves.
Expand Down
3 changes: 1 addition & 2 deletions examples/using-graphql-typegen/src/components/info.tsx
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import * as React from "react"
import { graphql } from "gatsby"


const Info = ({ buildTime }: { buildTime?: string | null }) => {
const Info = ({ buildTime }: { buildTime?: Queries.SiteInformationFragment["buildTime"] }) => {
return (
<p>
Build time: {buildTime}
Expand Down

0 comments on commit 0744cfd

Please sign in to comment.