Gatsby Cloud Docs

Getting started with Gatsby Preview and Cosmic JS

Learn how to connect Gatsby Preview with Cosmic JS

Table of Contents

What are Gatsby Cloud and Cosmic JS, and why use them together?

Cosmic JS is a headless CMS that content editors can use to edit and publish content. Gatsby Cloud allows you to integrate your site with Cosmic JS in order to run performant builds and preview content changes made in the CMS before publishing.

Signing in to Gatsby Cloud

Select 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 Cosmic JS requires several steps that are walked through below.

Creating an instance

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 manually integrate your site.

Add my own site

Pick your Gatsby site from the list of GitHub repositories. You can use the search input to narrow down the list.

Gatsby Cloud Add an instance page

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

Once the branch and directory path are correct, select “Next.”

Create the instance

Integration Step - automatic or manual

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

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

Automatic Integration

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

As an example, consider the following screenshot using Contentful:

Automatic Integration with Contentful

Once you’ve authorized {props.cmsTitle} and selected the appropriate organization, press “Create site” which will create your instance.

Manual Integration

First, click “Skip this step” to configure Cosmic JS 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 automatic detection may have 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!

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 a provided Gatsby Preview instance you can share with your team. Woo-hoo!


In order for Cosmic JS to inform Gatsby Cloud when content changes you’ll need to add a webhook. Let’s do it!

Getting the webhook

You will want to grab the value of the exposed webhook from Gatsby Cloud. This can be accessed via your Gatsby Cloud instance -> Site Settings -> Webhook. Copy this value as you’ll need it to get Cosmic JS working swimmingly with Gatsby Cloud.

Adding the webhook to Cosmic JS

With the webhook URL you’ve just copied, you should now go into your Cosmic JS bucket and add this webhook for a number of events, notably focusing on creates, updates, and deletes so that your Gatsby Cloud instance stays consistent with Cosmic JS.

Your webhooks will look something like this when finished:

Cosmic JS Webhooks

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 Cloud to authorize your instance to pull source data from Cosmic JS.

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:

Cosmic JS buckets typically have a bucket slug/id as well as a “read key,” both of which can be found Settings -> Basic Settings from the Cosmic JS sidebar.

Cosmic Environment Variables

You will want to grab these values and add them to your Gatsby Cloud instance. A typical naming convention will look like:

COSMIC_BUCKETThe bucket slug (or bucket id) for the Cosmic JS instance
COSMIC_READ_KEYThe read key for your Cosmic bucket

Select Next

Click Next and wait for the first instance to be generated. Now, when you change any copy or content in Cosmic JS, Gatsby Cloud should be up to date with your changes.