Understanding GraphQL Fragments in Gatsby

Written by TinjureWP Posted on

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.