Using GraphQL fragments across multiple templates in GatsbyJS
How to DRY up your static site templates with GraphQL
GatsbyJS is React-based framework for building static sites. Because Gatsby uses GraphQL as its data source, we can use a lot of helpful GraphQL features to help streamline our code. In this article, I’ll show how to use GraphQL fragments in Gatsby queries and how to share those queries across your project.
What are fragments?
GraphQL fragments are “reusable units” of query fields that can be used within the same query or across multiple queries.
Let’s use a GatsbyJS-powered blog as an example of how to make and reuse fragments.
In this example, our blog uses a template file blog-post.js to build pages for posts. The blog-post.js template has the markup for the post and has a GraphQL page query to fetch the data it needs. For a blog post, the page needs the post data, like the title and content, as well as information about the author to display a byline.
So we have a query like this in our blog-post.js template:
Using fragments
Seeing the separation between the posts’s fields and the author’s fields, we can use GraphQL’s fragments to help us organize a bit.
A fragment declares a unique name, what data type the fields belong to, then lists the wanted fields. The fragment is used in the query by using the spread operator … and the fragment name.¹
Noticing duplication
Now we have our query for a blog post, let’s think about a query for a blog-author.js template that displays author data, including a condensed view of each of their blog posts.
It would actually look very similar to our blog post query, since it needs the same fields from the author and posts.
We can implement fragments in our author query as well. Comparing our post and author queries, we see that fragments are identical.
Since we see the fragments are identical in the post and author templates, how do we share and reuse the fragments between template queries?
Exporting fragments in Gatsby
In the GraphQL Reference of the Gatsby documentation, it talks about fragments:
Fragments are a way to save frequently used queries for re-use. To create a fragment, define it in a query and export it as a named export from any file Gatsby is aware of. A fragment is available for use in any other GraphQL query, regardless of location in the project. Fragments defined in a Gatsby project are global, so names must be unique.
Great! So where do we put our fragments and what do “named exports” look like for our case.
To have a central place for our fragments where we can use them in both our templates, we created a fragments.js in our project’s src directory. Keep in mind, these exported fragments could be anywhere, so co-locating them in one file or spreading them out over more files is dependent on your team and project.
In fragments.js, we can copy our fragments, then turn them into Javascript named exports. As the reference quote above mentions, we need to make sure the names are unique.
Gatsby exports those queries to the global scope, so those fragments are now available in any other GraphQL query in the project. Since we kept the query names the same (postFields, authorFields), we don’t need to change our usage in the template queries.
Fragments Everywhere
Using GraphQL fragments inside GatsbyJS, we’re able to better organize our current queries, as well as, reuse parts across our project.
For the full example, see this code on Github.
[1] Having these fragments for only a few fields is definitely pre-optimizing, however, using fragments when there’s multiple objects with tens or hundreds of fields can help shorten and make clear even the longest query.
Resources:
Thanks for reading! Want to work on a mission-driven team that loves GatsbyJS and GraphQL? We’re hiring!
To learn more about Flatiron School, visit the website, follow us on Facebook and Twitter, and visit us at upcoming events near you.
Flatiron School is a proud member of the WeWork family. Check out our sister technology blogs WeWork Technology and Making Meetup.
