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.
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.
Once you’ve authenticated with Preview and GitHub, you can create a preview instance from the “Create a new Gatsby Cloud site” page.
We’ll be using the “I already have a Gatsby site” flow to manually integrate our 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 Preview works best with Gatsby version 2.1.0 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.
Once the branch and directory path are correct, select “Next.”
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!
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:
Finally, press “Create Preview Site” which will create your instance of Gatsby Preview.
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.
Once you’ve added the necessary environment variables, you can press “Create Preview Site” which will create your instance of Gatsby Preview!
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!
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:
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.
Open Contentful and select
Webhooks from the
Settings dropdown menu
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.
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.
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:
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.
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
gatsby-config.js file, check that your
contentfulConfig includes 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.
Example code (your exact settings may vary):
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.
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.
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 Preview, and Contentful. The following screenshot shows what the environment variables look like 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
CONTENTFUL_HOST key 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 Preview|
|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 just describes the variables you need in order for Gatsby Preview to generate your site’s preview instance.
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 Preview should be up to date with your changes.