gatsby-source-graphcms

The official Gatsby source plugin for GraphCMS projects

Demo • gatsby-starter-graphcms-blog • Join us on Slack • Login to GraphCMS • @GraphCMS

Installation

yarn add gatsby-source-graphcms gatsby-plugin-image

Note: Gatsby v4 requires Node.js >= 14.15.

Configuration

We recommend using environment variables with your GraphCMS token and endpoint values. You can learn more about using environment variables with Gatsby here.

Basic

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
      },
    },
  ],
}

Authorization

You can also provide an auth token using the token configuration key. This is necessary if your GraphCMS project is not publicly available, or you want to scope access to a specific content stage (i.e. draft content).

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        token: process.env.GRAPHCMS_TOKEN,
      },
    },
  ],
}

Options

Features

• Querying localised nodes
• Querying from content stages
• Usage with gatsby-plugin-image
• Downloading local image assets
• Using markdown nodes
• Working with query fragments

Querying localised nodes

If using GraphCMS localisation, this plugin provides support to build nodes for all provided locales.

Update your plugin configuration to include the locales key.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        locales: ['en', 'de'],
      },
    },
  ],
}

To query for nodes for a specific locale, use the filter query argument.

{
  enProducts: allGraphCmsProduct(filter: { locale: { eq: en } }) {
    nodes {
      name
    }
  }
}

Check out the demo source for an example of a localisation implementation.

Querying from content stages

This plugin provides support to build nodes for entries from multiple Content Stages.

The provided Content Stages must be accessible according to the configuration of your project’s API access. If providing a token, then that Permanent Auth Token must have permission to query data from all provided Content Stages.

The example below assumes that both the DRAFT and PUBLISHED stages are publicly accessible.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        stages: ['DRAFT', 'PUBLISHED'],
      },
    },
  ],
}

To query for nodes from a specific Content Stage, use the filter query argument.

{
  allGraphCmsProduct(filter: { stage: { eq: DRAFT } }) {
    nodes {
      name
    }
  }
}

Usage with gatsby-plugin-image

Requires gatsby-plugin-image as a project dependency.

This source plugin supports gatsby-plugin-image for responsive, high performance GraphCMS images direct from our CDN.

Use the gatsbyImageData resolver on your GraphCMS_Asset nodes.

{
  allGraphCmsAsset {
    nodes {
      gatsbyImageData(layout: FULL_WIDTH)
    }
  }
}

gatsbyImageData resolver arguments

NOTE: gatsby-plugin-sharp needs to be listed as a dependency on your project if you plan to use placeholder TRACED_SVG or DOMINANT_COLOR.

For more information on using gatsby-plugin-image, please see the documentation.

Downloading local image assets

If you prefer, the source plugin also provides the option to download and cache GraphCMS assets in your Gatsby project.

To enable this, add downloadLocalImages: true to your plugin configuration.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        downloadLocalImages: true,
      },
    },
  ],
}

This adds a localFile field to the GraphCMS_Asset type which resolves to the file node generated at build by gatsby-source-filesystem.

{
  allGraphCmsAsset {
    nodes {
      localFile {
        childImageSharp {
          gatsbyImageData(layout: FULL_WIDTH)
        }
      }
    }
  }
}

Using markdown nodes

This source plugin provides the option to build markdown nodes for all RichText fields in your GraphCMS schema, which in turn can be used with MDX.

To enable this, add buildMarkdownNodes: true to your plugin configuration.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        buildMarkdownNodes: true,
      },
    },
  ],
}

Enabling this option adds a markdownNode nested field to all RichText fields on the generated Gatsby schema.

You will need to rebuild your graphcms-fragments if you enable embeds on a Rich Text field, or you add/remove additional fields to your GraphCMS schema.

Usage with gatsby-plugin-mdx

These newly built nodes can be used with gatsby-plugin-mdx to render markdown from GraphCMS.

Once installed, you will be able to query for MDX fields using a query similar to the one below.

{
  allGraphCmsPost {
    nodes {
      id
      content {
        markdownNode {
          childMdx {
            body
          }
        }
      }
    }
  }
}

Check out the demo source for an example of a full MDX implementation.

Working with query fragments

The source plugin will generate and save GraphQL query fragments for every node type. By default, they will be saved in a graphcms-fragments directory at the root of your Gatsby project. This can be configured:

If using multiple instances of the source plugin, you must provide a value to prevent type and/or fragment conflicts.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-graphcms',
      options: {
        endpoint: process.env.GRAPHCMS_ENDPOINT,
        fragmentsPath: 'my-query-fragments',
      },
    },
  ],
}

The generated fragments are then read from the project for subsequent builds. It is recommended that they are checked in to version control for your project.

Should you make any changes or additions to your GraphCMS schema, you will need to update the query fragments accrdingly. Alternatively they will be regnerated on a subsequent build after removing the directory from your project.

Modifying query fragments

In some instances, you may need modify query fragments on a per type basis. This may involve:

• Removing unrequired fields
• Adding new fields with arguments as an aliased field

For example, adding a featuredCaseStudy field:

fragment Industry on Industry {
  featuredCaseStudy: caseStudies(where: { featured: true }, first: 1)
}

Field arguments cannot be read by Gatsby from the GraphCMS schema. Instead we must alias any required usages as aliased fields. In this example, the featuredCaseStudy field would then be available in our Gatsby queries:

{
  allGraphCmsIndustry {
    nodes {
      featuredCaseStudy {
        ...
      }
    }
  }
}

Contributors

Thanks goes to these wonderful people (emoji key):

Jonathan Steele 💻 📝 💡 🤔 🚧 📆

João Pedro Schmitz 💻 💡 🤔

Jamie Barton 💻 🐛 🚧 📖

If you spot an issue, or bug that you know how to fix, please submit a pull request.

When working locally you’ll need to run yarn compile and yarn dev using Yarn workspaces that will let you test/develop on the demo Gatsby app in this project. You may need to yarn clean occcasionally too.

FAQs

If you are using environment variables, make sure to include require("dotenv").config(); inside your gatsby-config.js.

If it’s already included, make sure you have your ENV variable added to .env, or .env.local without spaces.

This error occurs most likely if your token doesn’t have access to the PUBLISHED content stage. Configure your token to also access PUBLISHED, or specify stages: ["DRAFT"] to the options inside gatsby-config.js.

You may need to rebuild your fragments folder when making schema changes. If you change the type of a field, or add/remove any from an existing model you have fragments for, the plugin cannot query for this.

Simply delete the graphcms-fragments (or whatever you named it), and run gatsby develop to regenerate.