Getting Started with Gatsby Cloud and Contentful
See how to connect Gatsby Cloud with Contentful
Table of Contents
Contentful is a headless CMS that content editors can use to edit and publish content. Gatsby Cloud allows you to integrate your site with Contentful in order to run performant builds and preview content changes made in the CMS before publishing.
To enable you to make previews a lot faster, this doc will also show you how to setup the Contentful sidebar with Preview. This is what the Gatsby Preview button will look like once finish going through the steps in this doc.
Sign in with GitHub. You’ll be asked to authorize the Gatsby Cloud app with your GitHub account. If you need to request access to one or more repositories, you can click “request access” here or later, when creating an instance.
Once signed in, configuring Gatsby Cloud with Contentful requires several steps that are walked through below.
Once you’ve authenticated with Cloud and GitHub, you can create an instance from the “Create a new Gatsby Cloud site” page.
Use the “I already have a Gatsby site” flow to setup your existing site.
Pick your Gatsby site from the list of GitHub repositories. You can use the search input to narrow down the list.
If you don’t see your site, it might be because it belongs to a GitHub organization, rather than your personal account. You can connect a new GitHub Organization.
Note: Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Cloud works best with Gatsby version 2.20.16 and higher.
You’ll need to select a branch and then indicate the publish directory where the
gatsby-config.js lives. If you leave the field blank, it defaults to the root of the site. Optionally, you may change the site name.
Once the branch and base directory are correct, select “Next.”
Find Contentful in the list, press “Connect” and follow the set-up instructions to link Contentful with Gatsby Cloud.
Once you’ve authorized Contentful and selected the appropriate organization, press “Create site” which will create your instance.
If you'd rather not use Quick Connect follow the steps below:
First, click “Skip this step” to configure Contentful.
Gatsby Cloud will automatically try and detect environment variables necessary in your
gatsby-config.js. However — you may need to add any additional variables that automatic detection missed. See “Setting up Environment Variables” for more info.
Note that you will be able to add, delete, or update these later on in “Site Settings”.
Once you’ve added the necessary environment variables, you can press “Create site” which will create your instance in Gatsby Cloud!
An environment variable references a value that can affect how running processes will behave on a computer, for example in staging and production environments. You must save environment variables in Gatsby Cloud to authorize your instance to pull source data from Contentful.
You will need to add into Gatsby Cloud any environment variable required for your app to run, such as deployment or test environment configuration settings.
You will also need to add in the following Gatsby Cloud-specific environment variables:
- Contentful Space ID
- Contentful Preview API access token
- Contentful Host
These environment variables need to be in both your
gatsby-config.js and your Gastby Site settings with identical names so your instance knows how to find them in your Gatsby Cloud settings.
Note that you can set environment variables for both Preview and Builds, allowing you to use different values as needed. Consider the difference as staging versus production environments. You likely want to see draft content in Preview, but not in Build.
In your gatsby-config.js file, follow these steps:
In GitHub, navigate to the Gatsby site you selected for your instance
Navigate to the
gatsby-config.jsfile at the root of the site - If you don’t have a
gatsby-config.jsfile, create one
gatsby-config.jsfile, check that your
contentfulConfigincludes these 3 items -
gatsby-config.js file does not contain the three environment variables above, add them to the file and save the changes, making sure the changes have been pushed to your repository on GitHub.
If you have additional environment variables listed in your
gatsby-config.js file that are necessary for your app to run, you’ll also need to include those environment variables in Gatsby Cloud.
Next, you’ll need to copy environment variables from Contentful and paste them into your “Site Settings” in the Gatsby Cloud app. The order of the variables does not matter.
Select API Keys from the Settings dropdown menu
From the list, select the site you want to view API Keys for. If you haven’t generated the API Keys you want for your site yet, generate
SPACE ID and
ACCESS TOKENS in Contentful by following these instructions.
You’ll need to use the same environment variables in the
gatsby-config.js file, Gatsby Cloud, and Contentful. The following screenshot shows what the environment variables look like in Contentful.
Copy and paste the following into the Preview and/or Builds Environment Variables section:
Contentful Space ID value to the
CONTENTFUL_SPACE_IDenvironment variable field in the Gatsby Cloud dashboard.
Contentful Preview API access token value to the
CONTENTFUL_ACCESS_TOKENenvironment variable field in the Gatsby Cloud dashboard
CONTENTFUL_HOSTkey and set the value to preview.contentful.com
If the above three steps are a little confusing, it’s because the names of the environment variables vary across platforms. This table shows what the environment variables are called in each platform.
|What it’s called in ||What the ||What value to enter in Gatsby Cloud|
|We recommend ||Must match the environment variable name in ||Copy the Space ID from Contentful|
|We recommend ||Must match the environment variable name in ||Copy the Content Preview API - access token from Contentful|
|We recommend ||Must match the environment variable name in ||preview.contentful.com|
You can add and remove as many environment variables as you want. The previous section focuses only on the variables that are required for Gatsby Cloud to integrate with your CMS.
To make a connection between Contentful and Gatsby Cloud for your site, you’ll need to configure a webhook in Contentful so that content changes can be pushed to Gatsby Cloud.
You can add and edit necessary webhook information in two places in Gatsby Cloud:
- During the “Create a new Site” process
- After setting up an instance, on that instance’s Settings page
In “Create the instance” we created a Gatsby Cloud instance which exposed a webhook. We’ll use that exposed webhook now.
Navigate to your Gatsby Cloud instance, and press “Site Settings.” Copy the Webhook on this page.
Open Contentful and select
Webhooks from the
Settings dropdown menu
Save to save these changes. If you don’t click save and attempt to navigate to another page in Contentful, Contentful will prompt you to save the information.
To make it easy for team members working in Contentful to launch Gatsby Preview and to make previews a lot faster, install an extension to enable an “Open Preview” link in the Contentful UI using the doc ”Add the Gatsby Preview Extension to Contentful“.
Now, when you change any copy or content in Contentful, Gatsby Cloud should be up to date with your changes.