Gatsby Cloud Docs

Getting started with Gatsby Preview and Contentful

See how to connect Gatsby Preview with Contentful

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 3 steps that are walked through below:

  1. Creating a preview instance on Gatsby Preview

  2. Setting up a webhook between Gatsby Preview and Contentful

  3. Adding environment variables to your site and to Gatsby Preview

1. Creating a preview instance

Once you’ve authenticated with Preview and GitHub, you can create a preview instance from the dashboard/sites/create page.

Gatsby Preview Add a preview instance page

Select your organization from the dropdown menu and then select your site using the search bar or from the list.

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.

2. Webhooks: Configuring your Gatsby site to work with Gatsby Preview and Contentful

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: https://www.contentful.com/developers/docs/concepts/webhooks/

Adding a webhook

Pick the repository and site you want to use

Add a new site to Preview page with organization drop down and site highlighted

Copy the webhook link to your clipboard

Gatsby Preview image of Webhook integration link example

Open Contentful and select Webhooks from the Settings dropdown menu

Settings dropdown in Contentful 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.

Finding the webhook on an existing Preview instance

Go to the Settings page for your preview instance. You’ll see the webhook integration link under your environment variables. image of preview instance Settings page highlighted in Gatsby Preview

3. 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 preview.contentful.com

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 file What the key is called in Gatsby Preview What value to enter in Gatsby Preview
We recommend CONTENTFUL_SPACE_ID, but you could call it anything Must match the environment variable name in gatsby-config.js Copy the Space ID from Contentful
We recommend CONTENTFUL_PREVIEW_ACCESS_TOKEN, but you could call it anything Must match the environment variable name in gatsby-config.js Copy the Content Preview API - access token from Contentful
We recommend CONTENTFUL_HOST, but you could call it anything Must match the environment variable name in gatsby-config.js preview.contentful.com

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

Finished

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