How to setup the Gatsby Source Craft Plugin

Oscar de la Hera Gomez
<p></p>
<p>Three flowers that represent Craft CMS, GraphQL and GatsbyJS side by side. Beneath them sits the text “gatsby-source-craft”.</p>
<p></p>

A step by step guide on setting up Craft CMS and Gatsby to work with the gatsby-source-craft plugin.

Shout out to Brian J Hanson and the good people at Craft for writing the plugin and taking the time to help me figure this out.

This plugin has produced a 10-100x performance improvement and has allowed delasign to maximize the potential of our modular web systems.

Step One: Setup Craft CMS to Work with the GraphQL

A screenshot of the Craft CMS project with the general.php file open highlighting how we enabled GraphQL.

Follow the tutorial below to setup Craft CMS to work with the GraphQL

Step Two: Add the Gatsby Helper Plugin

<p>A screenshot of Craft CMS's plugin store highlighting how to find the Gatsby Helper Plugin.</p>

Add the Gatsby Help dependency by running the following line in Terminal with the current directory set to that of your Craft CMS project.

Make sure that the plugin uses v2.0.2 or higher to avoid it breaking on update.

composer require craftcms/gatsby-helper -w && php craft plugin/install gatsby-helper

Step Three: Allow discovery of sourcing data for Gatsby

<p>A screenshot of a Craft CMS GraphQL Schema page, highlighting how to allow Gatsby to source GraphQL data using the Gatsby Helper plugin.</p>

In your GraphQL Schema, navigate to the Gatsby section and make sure Allow discovery of sourcing data for Gatsby. is turned on.

Step Four: Add the gatsby-source-craft plugin

<p>A screenshot of terminal showing you how to add the gatsby-source-craft plugin to Gatsby. Code available below.</p>

Add the gatsby-source-craft plugin to your GatsbyJS project by running the following line in Terminal with the current directory set to that of your GatsbyJS project.

yarn add gatsby-source-craft

Step Five: Add the Environment Variables

<p>A screenshot of VSCode highlighting the environment variables that you have to add to the .env file. Details listed below.</p>

Add the following two environment variables to your GatsbyJS .env file.

A | CRAFTGQL_URL

Add a CRAFTGQL_URL environment variable with the string value equal to that of the GraphQL API of your Craft CMS.

B | CraftGQL_Token

Add a CRAFTGQL_Token environment variable with the string value equal to that of the GraphQL Token of your Craft CMS.

Please note that if your token is Authorization: Bearer xafslafksafnlsasa you must only enter the xafslafksafnlsasa value

Step Six: Update the Gatsby Config

<p>A screenshot of VSCode showing how we added the gatsby-source-craft plugin to the gatsby-config.js file. Code available below.</p>

In the GatsbyJS project, add the gatsby-source-craft plugin to the configuration using code similar to the one shown below:

To discover all the options consult the link below.

Step Seven: Run

<p>A screenshot of Terminal showing how Gatsby fetches the schema for the GraphQL.</p>

As Gatsby gathers the schema from Craft you will see something similar to that above.

Run the gatsby develop command in Terminal with the current directory set to that of your GatsbyJS project to confirm that everything works.

Next Steps: Write the Queries

<p>A screenshot of Gatsby's GraphiQL showing a gatsby-source-craft query.</p>

GraphQL queries using the gatsby-source-craft plugin don't work the same as GraphQL queries.

This is part of the magic of this plugin, which may cause pain to begin with but streamlines your process down the line.

To learn how to configure queries, open the GraphiQL found at the __graphql extension (i.e. localhost:8000/__graphql).

Frequently Asked Questions (FAQ)

I can't get past the source and transform nodes

This is likely because your process is too intensive for your server. Before upgrading your servers power, try the following things:

  • Setting concurrency to 1 in the gatsby-source-craft options within the gatsby-config.js file.
  • Adding the following environment variable GATSBY_CPU_COUNT=1

The above two items will make sure that only 1 GraphQL call is made at a time (i.e. FIFO - First In First Out).

If that doesn't work, try increasing your Craft CMS's max_execution_time to the highest possible value.

I'm getting an error that starts with "cannot query field"

As mentioned above, GraphQL queries using the gatsby-source-craft function differently than normal GraphQL queries.

This applies to globalSets, entries, entry and pretty much every other standard GraphQL element.

If you are migrating, we recommend creating a clean project that launches the GraphiQL and use that to determine all the new queries.

I'm getting an error that starts with "Unknown argument"

As mentioned above, GraphQL queries using the gatsby-source-craft function differently than normal GraphQL queries.

This applies to limits, offsets and many other standard GraphQL arguments.

If you are migrating, we recommend creating a clean project that launches the GraphiQL and use that to determine all the new queries.

My query arguments no longer works

As mentioned above, GraphQL queries using the gatsby-source-craft function differently than normal GraphQL queries.

This applies to QueryArguments within the each page query.

If you are migrating, we recommend creating a clean project that launches the GraphiQL and use that to determine all the new queries.

The id of the entry doesn't match what I had before

Brian let us know that the id property in the gatsby-source-plugin is remoteId.

An example of how to filter by Id is found below. If you are using a QueryArgument, make it have the type value of ID.

I can't get the Algolia source plugin working

As mentioned above, GraphQL queries using the gatsby-source-craft function differently than normal GraphQL queries.

If you are migrating, we recommend creating a clean project that launches the GraphiQL and use that to determine all the new queries.

Does it work with Gatsby v5 or higher ?

It does !

My issue isn't listed

Ping us a note or contact Craft CMS for other issues.

Any Questions ?

We are actively looking for feedback on how to improve this resource. Please send us a note to inquiries@delasign.com with any thoughts or feedback you may have.
delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details