Sourcing and Querying Content in Gatsby


Sourcing content from Gatsby with Agility CMS uses the gatsby-source-agilitycms plugin, however for an example of how this works in a real website, see the agilitycms-gatsby-starter.

Using the gatsby-source-agilitycms plugin will mean that all of your content, modules, sitemaps, and pages will be synchronized with your Gatsby site and available via GraphQL.

In this guide, we'll cover:

  1. Configuring the Plugin
  2. How does Sourcing Content Work
  3. Querying Content

Configuring the Plugin

The plugin is registered in the gatsby-config.js file in your Gatsby site along with several configurable options that influence the behaviour of the plugin.

  path: `.env.${process.env.NODE_ENV}`,

//configure your agility plugin with environment variables so that
//your agility api credentials stay secure
const agilityConfig = {
  guid: process.env.AGILITY_GUID,
  apiKey: process.env.AGILITY_API_KEY,
  isPreview: process.env.AGILITY_API_ISPREVIEW === "true"
module.exports = {
    plugins: [
      //the name of the plugin
      resolve: "@agility/gatsby-source-agilitycms", 
      //the options for our plugin
      options: {
        //your Agility Content Fetch API Guid
        guid: agilityConfig.guid, 
        //your Agility Content Fetch API Key
        apiKey: agilityConfig.apiKey, 
        //set this to true if you are using the preview API Key
        isPreview: agilityConfig.isPreview, 
        //set this to true to see expanded traces in the build logs
        debug: false,
        //the languages you want to source content for
        languages: [{
          // The name of the language code
          name: "English",
          // The actual language code set in Agility CMS
          code: "en-us", 
          // The name to be used in the URL path that represents the current language
          path: "en"
        // The channels you want to include
        channels: [{
          // The reference name for the website channel as it is defined in Agility CMS
          referenceName: "website"
         //the page template that will be used to render Agility CMS pages
        masterPageTemplate: "./src/AgilityPage.jsx"

How Sourcing Content Works

The source plugin uses the @agility/content-sync npm package which ensures that only content that has changed is updated. It keeps things in-sync for you.

This means your first build will download all of your content, while subsequent builds only update what has changed. This enables incremental builds and results in bleeding-edge, fast build times.

Need to Resync?

If you want to force a full-resync (clears all cached/sourced content), you can run:

gatsby clean

The next time you run gatsby develop or gatsby build it will source and download all of your content again.

Accessing your Content

All of your content is downloaded and stored in the Gatsby GraphQL. You can explore all of the content in your GraphQL and auto-generate queries for you to use in your Gatsby site.

When running your site locally using gatsby develop, you can view the GraphQL Playground by navigating to http://localhost:8000/___graphql.


Rebuild to update Content

In order for content from the CMS to be refreshed, you need to re-build the site. You can do this locally by re-running gatsby develop

Querying Content


To query content from Agility CMS, you would query allAgility<contentTypeName>, for example, allAgilityPost, then select what fields you want to retrieve for each item.

query MyPosts {
  allAgilityPost {
    nodes {
      customFields {
        image {

Page Modules

To query modules on pages from Agility CMS, you would query allAgility<moduleTypeName>, for example, allRichTextArea, then select what fields you want to retrieve for each item.

query MyRichTextAreaQuery {
  allAgilityRichTextArea {
    nodes {
      customFields {


To query a page from Agility CMS, you would query allAgilitypage.


Pages store information pertaining to which modules and their fields are on the page, so due to the dynamic nature of this data, there is only a single pageJson property that contains the page fields serialized into a string.

You can easily convert this into an object within the Gatsby site and pass each module's fields as props to your react components responsible for rendering each module. This is exactly how the agilitycms-gatsby-starter site is configured.

query MyPageQuery {
  allAgilitypage {
    nodes {


To query a sitemap from Agility CMS, you would query allAgilitySitemapNode.

query MySitemapQuery {
  allAgilitySitemapNode {
    nodes {



3 out of 3 found this helpful



Please sign in to leave a comment.