Note: This note is part of learning Gatsby series and still in development. This note is not complete and will be updated frequently.
GraphQL query may contains query definitions and fragments. Fragments are selection of query definitions that can be re-used in multiple operations. The concept of query fragments is “to split complicated application data requirements into smaller chunks, especially when you need to combine lots of UI components with different fragments into one initial data fetch”.
What is Fragment?
In Gatsby, use of GraphQL fragments is common. First of all what are Fragments? According to the Gatsby Doc, “GraphQL includes a concept called “query fragments”. Which, as the name suggests, are a part of a query that can be used in multiple queries.” For example, gatsby-image
plugin ships with various built-in image processing query fragments which can be directly used with supporting plugins, like gatsby-transformer-sharp.
One of the commonly used example of using built-in fragment is for querying images, ...GatsbyImageSharpFixed
, which is a GraphQL Fragment, a reusable set of fields for query composition.
Some benefits of using fragments include splitting complex query definitions into smaller re-usable parts, consistency in code and better readability.
Fragments Syntax
A very basic syntax of fragment consists of three components:
""" fragment basic syntax"""
fragment FragmentName on TypeName {
field1
field2
}
FragmentName
: This is the name of fragment that is called later in another queries;TypeName
: the GraphQL type of the object the fragment will be used on. The query fields that actually exist on a given object can only be used.- The body of the query. You can define any fields with any level of nesting in here
Lets create a simple example of Fragment (with file name Author-info.js
) to query author information:
// author info fragment
export const query = graphql`
fragment Author on AuthorInfo {
id
name
slug
web
}
`
In the example above, Author
is the FragmentName
and that will be used to query the fields in another component , and AuthorInfo
is the GraphQL type and the body is value.
Using Fragments in Another Component
Now the Author-info.js
fragment can be used in another component, lets say, blogIndex.js
// src/components/blogIndex.js
import React from "react"
import { graphql } from "gatsby"
import Author from "../components/Author-info"
const BlogIndex ({data}) => {
// Use the `data` property here...
}
export const query = graphql`
query {
author {
... Author
}
}
`
After the Fragment file is imported, now the Author fragment can be used within the BlogIndex page GraphQL query. When the file is processed, the GraphQL will process the query fields defined in Fragment body.
An Use Case Example
An simple use case example, for the illustration purposes, is taken from the using-gatsby-source-wordpress-experimental authored by Tyler Barnes.
// source: using-gatsby-source-wordpress-experimental
import { graphql } from "gatsby"
export const fragments = graphql`
fragment HeroImage on File {
childImageSharp {
fluid(maxWidth: 1440) {
...GatsbyImageSharpFluid_withWebp_tracedSVG
}
}
}
The code snippets is directly lifted from the src/fragments.js
file. A fragment file may contain several query fragments. Now this fragment can be used in other queries.
Calling Fragments in Components
The post.js
component of the using-source-wordpress-experimental starter shown below. The HeroImage
fragment created in the previews step has been inside its query, after remoteFile
(line 18).
// src/templates/single/post.js
// source: using-gatsby-source-wordpress-experimental
import React from "react"
import { graphql } from "gatsby"
import BlogPost from "../../components/template-parts/blog-post"
export default ({ data }) => <BlogPost data={data} />
export const query = graphql`
query post($id: String!, $nextPage: String, $previousPage: String) {
page: wpPost(id: { eq: $id }) {
title
content
featuredImage {
node {
remoteFile {
...HeroImage
}
}
}
}
nextPage: wpPost(id: { eq: $nextPage }) {
title
uri
}
previousPage: wpPost(id: { eq: $previousPage }) {
title
uri
}
}
`
In the example code above, the HeroImage
fragments created in the previous section is called in src/templates/single/post.js
component (line 18) as ...HeroImage
fragment. The HeroImage
fragment can also be re-used in any other query of other components.
Example from Eve Porcello
In a dev.to post, Eve Porcello has another use case example of GraphQL fragments.
Wrapping Up
In this brief note, what are fragments, their syntax and an example use case was discussed. Fragments are most frequently used features in gatsby image plugins.
Useful References
While preparing this post, I have referred the following references extensively. Please refer to original posts for more detailed information.
- Using GraphQL Fragments | Gatsby Doc
- Fragments – GraphQL Doc
- Querying Data with GraphQL – Fragments
- Understanding Fragments in GraphQL by Eve Porcello | Dev.to