Gatsby Cloud Docs

Getting Started with Gatsby Cloud and Contentful

See how to connect Gatsby Cloud with Contentful

Table of Contents

What are Gatsby Preview and Contentful, and why use them together?

Contentful is a headless CMS that content editors can use to edit and publish content. Gatsby Preview allows developers and content editors to preview code and content changes made in the CMS before publishing those changes.

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.

Contentful Preview button in the sidebar

Signing in to Gatsby Preview

Select Sign in with GitHub. You’ll be asked to authorize the Gatsby Preview 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 a preview instance.

Once signed in, configuring Gatsby Preview with Contentful requires several steps that are walked through below.

Creating a preview instance

Once you’ve authenticated with Preview and GitHub, you can create a preview instance from the “Create a new Preview instance” page.

We’ll be using the “Add my own site” flow to manually integrate our site.

Add my own site

Select your organization from the dropdown menu and then select your site using the search bar or from the list. Consider using the “Search your Github repositories” searchbar to narrow down your sites.

Gatsby Preview Add a preview instance page

Preview will list each organization that you have permission for in a dropdown, allowing you to work with more than one organization’s repositories.

Note: Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Preview works best with Gatsby version 2.1.0 and higher.

Select branch and publish directory

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.

Select branch and directory

Select “Next” once you’ve filled in the branch and publish directory—or if the defaults are good to go!

Create the instance

Integration Step - automatic or manual

If you have already configured an instance of Contentful or if you don’t see Contentful in the “Automatic Provisioning” list, skip to Manual Integration.

If you do see Contentful in the “Automatic Integrations” section, consider using the “Automatic Integration” flow and Gatsby Cloud will set-up your CMS for you!

Automatic Integration

Find Contentful in the automatic integrations section, press “Connect” and follow the set-up instructions to link Contentful with Gatsby Cloud.

As an example, consider the following example using Contentful:

Automatic Integration with Contentful

Finally, press “Create Preview Site” which will create your instance of Gatsby Preview.

Manual Integration

First, click “Skip this step” to configure Contentful manually.

Gatsby Cloud will automatically try and detect environment variables necessary in your gatsby-config.js. However — consider adding any additional ones or variables that our automatic detection may have missed. See “Setting up Environment Variables” for more info.

Adding environment variables

Once you’ve added the necessary environment variables, you can press “Create Preview Site” which will create your instance of Gatsby Preview!

Site is Created

After following the “Automatic Integration” or “Manual Integration” flow you now have an instance of Gatsby Cloud configured with environment variables and an provided Gatsby Preview instance you can share with your team. Woo-hoo!

Gatsby Preview Created

Webhooks: Configuring your Gatsby site to work with Gatsby Preview

Setting up a webhook in Contentful

To make a connection between Contentful and Gatsby Preview for your site, you’ll need to configure a webhook in Contentful so that content changes can be pushed to Gatsby Preview.

You can add and edit necessary webhook information in two places in Gatsby Preview:

  • During the “Create a new Preview” process
  • After setting up a preview instance, on that preview instance’s Settings page

Contentful documentation on webhooks

Adding a webhook

In “Create the instance” we created a Gatsby Preview instance which exposed a webhook. We’ll use that exposed webhook now.

Navigate to your Gatsby Preview instance, and press “Settings.” Copy the Webhook on this page.

Copying the webhook URL

Open Contentful and select Webhooks from the Settings dropdown menu

Settings dropdown in <span children={props.cmsTitle} /> with Webhooks option highlighted

Select Add Webhook

Image of add webhook button highlighted

Name your Gatsby Preview webhook. Leave the URL setting to POST and paste the webhook link you copied from the Gatsby Preview dashboard. You can leave the Triggers section set to Trigger for all events. image of webhook details page

Click 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.

Setting up Environment Variables

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 Preview to authorize your preview instance to pull source data from Contentful.

You will need to add into Gatsby Preview 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 Preview-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 Preview settings with identical names so your Preview instance knows how to find them in your Gatsby Preview settings.

Environment variables in your gatsby-config.js:

In your gatsby-config.js file, follow these steps:

  • In GitHub, navigate to the Gatsby site you selected for your preview instance

  • Navigate to the gatsby-config.js file at the root of the site - If you don’t have a gatsby-config.js file, create one

  • In the gatsby-config.js file, check that your contentfulConfig includes these 3 items - CONTENTFUL_SPACE_ID - CONTENTFUL_PREVIEW_ACCESS_TOKEN - CONTENTFUL_HOST

image of contentfulConfig environment variables

If your 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.

Example code (your exact settings may vary): image of gatsby-js.config file code example

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 Preview.

Copy your environment variables to Gatsby Preview

Next, you’ll need to copy environment variables from Contentful and paste them into your settings in the Gatsby Preview app. The order of the variables does not matter.

Finding your Space ID and Preview API Access Token in Contentful

Select API Keys from the Settings dropdown menu

Image of settings dropdown in Contentful with API keys option highlighted

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.

image of API site list options in Contentful

You’ll need to use the same environment variables in the gatsby-config.js file, Gatsby Preview, and Contentful. The following screenshot shows what the environment variables look like in Contentful.

image of Space ID and Preview access token APIs highlighted in Contentful

Copy and paste the following:

  • Contentful Space ID value to the CONTENTFUL_SPACE_ID environment variable field in the Gatsby Preview dashboard.

  • Contentful Preview API access token value to the CONTENTFUL_PREVIEW_ACCESS_TOKEN environment variable field in the Gatsby Preview dashboard

  • Add the CONTENTFUL_HOST key and set the value to

image of required environment variables in Gatsby Preview

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 gatsby-config.js fileWhat the key is called in Gatsby PreviewWhat value to enter in Gatsby Preview
We recommend CONTENTFUL_SPACE_ID, but you could call it anythingMust match the environment variable name in gatsby-config.jsCopy the Space ID from Contentful
We recommend CONTENTFUL_PREVIEW_ACCESS_TOKEN, but you could call it anythingMust match the environment variable name in gatsby-config.jsCopy the Content Preview API - access token from Contentful
We recommend CONTENTFUL_HOST, but you could call it anythingMust match the environment variable name in

Select Next

Adding more environment variables

You can add and remove as many environment variables as you want. The previous section just describes the variables you need in order for Gatsby Preview to generate your site’s preview instance.

Adding the Gatsby Preview button to Contentful

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“.

Contentful Preview button in the sidebar


Now, when you change any copy or content in Contentful, Gatsby Preview should be up to date with your changes.