Gatsby Cloud Docs

Getting started with Gatsby Cloud and Kontent

Learn how to connect Gatsby Cloud with Kentico Kontent

Table of Contents

In this tutorial you will discover how to easily integrate site sourced by Kentico Kontent with Gatsby Cloud.

You will

  • Create a website using data from Kentico Kontent.
  • Store its source Code on GitHub.
  • Register this Github repository in Gatsby Cloud.
  • Configure Kentico Kontent webhooks to notify Gatsby Cloud about the content changes on preview environment as well as on production.
  • Configure preview URLs in Kentico Kontent.

What are Gatsby Cloud and Kontent, and why use them together?

Kontent is a headless CMS that content editors can use to edit and publish content. It is a Content-as-a-Service solution that gives enterprises control over their entire content lifecycle in a single unified environment. Gatsby Cloud allows you to integrate your site with Kontent in order to run performant builds and preview content changes made in the CMS before publishing.

Setting up a Kontent and Gatsby site

First, you’ll need a Gatsby site with a gatsby-source-kontent source plugin to pull data from Kontent. If you haven’t set that up yet, you can quickly create a new project by using the gatsby-starter-kontent-lumen repository. For detailed guidance on working with this starter, see the Getting started tutorial.

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 Kontent 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 setup your existing 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.20.16 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. Optionally, you may change the site name.

Select branch and directory

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

Create the instance

Integration Step

Manual Setup

First, click “Skip this step” to configure Kontent.

Gatsby Cloud will automatically try and detect environment variables necessary in your gatsby-config.js. However — you may need to add any additional variables that automatic detection 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!

Setting up Environment Variables

An environment variable references a value that can affect how running processes will behave in a specific environment, such as staging and production environments. You must save your environment variables in Gatsby Cloud to authorize your instance to pull source data from Kontent.

First, open your Kontent project and go to Project settings > API Keys. On the API keys screen, copy the values for Project ID and Preview API key (Primary or Secondary).

Kontent API keys section

Then go to Project settings > Localization to get the codenames of your project languages.

Kontent Localization configuration section

The language codenames used in the gatsby-starter-kontent-lumen sample app are en-US,cs-CZ.

ValueEnvironment Variable Name
<YOUR_PROJECT_ID>KONTENT_PROJECT_ID
<YOUR_PREVIEW_API_KEY>KONTENT_PREVIEW_KEY
<YOUR_LANGUAGE1,YOUR_LANGUAGE2>KONTENT_LANGUAGE_CODENAMES

You will want to set KONTENT_PREVIEW_ENABLED to true for Preview and false for Builds.

Environment variables

Once you’ve entered your variables, click Save and then Create site.

Go to the Preview tab and wait for the preview instance to be created.

Webhooks: Configuring your Gatsby site to be updated with content changes

To connect Kontent with your Gatsby Cloud instance, you’ll need to configure a webhook in Kontent so that content changes can be pushed to Gatsby Cloud.

You’ll add two webhooks in Kontent: one for Gatsby Preview and another for Gatsby Builds.

Following webhooks could be also added via Management API.

Adding a Preview Webhook

Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Preview Webhook on this page.

Copying the Preview webhook URL

In your Kentico Kontent project, go to Project settings > Webhooks and click Create new webhook.

Kontent webhooks menu

Name the webhook and paste the Preview webhook into the URL address field.

In the webhook configuration, select the Create or Update and Delete triggers under DELIVERY PREVIEW API TRIGGERS. Then remove Publish, Unpublish, Delete, Restore, and Create or Update triggers from DELIVERY API TRIGGERS by using the cross next to them. You should end up with the following configuration.

Kontent preview webhook configuration

Click Save.

Your Preview webhook is now ready! When you change your content in Kontent, your Gatsby Preview will update!

Adding a Builds Webhook

Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Builds Webhook on this page.

Copying the Builds webhook URL

In Kentico Kontent, go to Project settings > Webhooks and click Create new webhook.

Kontent webhooks menu with one webhook

Name the webhook and paste the Builds webhook in the URL address field.

In the webhook configuration, make sure only the Publish and Unpublish triggers are selected under DELIVERY API TRIGGERS.

Kontent builds webhook configuration

Click Save.

Your Builds webhook is now ready! When you publish/unpublish content in Kontent, your Gatsby Builds will update!

Setting the Gatsby Preview Domain for Kontent

To open the Gatsby Cloud preview right from Kentico Kontent, you need to configure preview URLs for your content. The following instructions assume you’re using the gatsby-starter-kontent-lumen sample app.

Navigate to your Gatsby Cloud instance and click Preview. Copy the preview URL.

Gatsby cloud preview URL

In Kentico Kontent, go to Project settings > Preview URLs and provide the URLs according to your routes configuration.

Preview URLs configuration

Now you can open the content preview right from Kentico Kontent UI!

Preview button showcase in Kontent

Wrapping Up

At this point, you have a Kontent instance configured to best support Gatsby Cloud. Edit content, click the Preview button, and watch it appear live in Gatsby Cloud!

© 2020 Gatsby, Inc.