Gatsby Cloud Docs

Getting started with Gatsby Preview and Contentstack

Learn how to connect Gatsby Preview with Contentstack

Table of Contents

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

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

Setting up a Contentstack and Gatsby site

First, you’ll need a Gatsby site that’s pulling source data from a Contentstack project via the gatsby-source-contentstack plugin and its source code needs to live on GitHub. If you haven’t set that up yet, try using the gatsby-starter-contentstack starter.

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 Contentstack 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 Contentstack or if you don’t see Contentstack in the “Automatic Provisioning” list, skip to Manual Integration.

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

Automatic Integration

Find Contentstack in the automatic integrations section, press “Connect” and follow the set-up instructions to link Contentstack 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 Contentstack 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

Configuring Preview Webhooks

In Contentstack, navigate to Settings using the gear icon and then to “Webhooks”. Select “create new webhook.” Navigate to Gatsby Preview, and then to the Settings for your Gatsby Preview instance. Copy the webhook URL, navigate back to Contentstack webhook, and paste the webhook URL into the field labelled “URL to notify *“.

A screenshot showing where to copy and paste the Gatsby webhook into Contentstack

In Contentstack, there are options to add webhook responses to certain events. Add all the options you’d like. A best practice is to add webhook responses for nearly everything you can! For example, select any content type, asset, or entry and add responses for any options available, such as create, update, delete, successful publish, and unsuccessful publish.

A screenshot showing examples of webhook options

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

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:

  1. In your Contentstack account, navigate to Settings using the gear icon in the menu and select “Environments”.

  2. Create an environment named “Preview”, and omit the Base URL for now. It will be filled in later.

  3. Navigate to Settings using the gear icon again and select “Tokens”.

  4. Create a new token, give it a name and add it to the scope for the “Preview” environment.

A screenshot showing how to add the token to the preview environment

  1. After creating the token you will see an API token and a Delivery Token. You will add these values as environment variables in Gatsby Preview.

This matches the gatsby-config.js of the site:

module.exports = {
  plugins: [
      resolve: "gatsby-source-contentstack",
      options: {        api_key: process.env.CONTENTSTACK_API_KEY,        access_token: process.env.CONTENTSTACK_ACCESS_TOKEN,        environment: process.env.CONTENTSTACK_ENVIRONMENT,      },    },

Select Next

Select Next and wait for the first preview instance to be created.

Configuring the Preview Environment

After your Preview instance is created, copy the Preview instance URL. Then navigate to your Contentstack stack’s setting (gear icon), navigate to “Environments”, edit the preview environment, and paste the Gatsby Preview URL as the base URL.

Testing Gatsby Preview instance

When you publish changes to your content in Contentstack, your Gatsby Preview instance should update quickly.