Gatsby Cloud Docs

Getting started with Gatsby Cloud and Strapi

Learn how to connect Gatsby Cloud with Strapi

Table of Contents

Getting Started with Strapi

If you are new to Strapi or are just looking to test a Gatsby Cloud and Strapi integration, the strapi-starter-gatsby-blog repo is a good way to get up and running quickly! The project readme has specific set up instructions for setting up your first Strapi project that will help you get it working with Gatsby Cloud.

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

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

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 variable:

  • Strapi API_URL: the URL to your Strapi instance. If you are following along with the Strapi starter, you can quickly test by exposing the Strapi instance on your localhost with a tool like ngrok or you can follow the Strapi documentation on deployments.

This environment variable needs to be in both your gatsby-config.js and your Gastby Site settings with identical names so your instance knows how to find them in your Gatsby Cloud settings.

Note that you can set environment variables for both Preview and Builds, allowing you to use different values as needed. Consider the difference as staging versus production environments. You likely want to see draft content in Preview, but not in Build.

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 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 gatsby-source-strapi config contains the API_URL.

It should look something like this:

If your gatsby-config.js file does not contain the API_URL environment variable, add them to the file and save the changes, making sure the changes have been pushed to your repository on GitHub.

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

Adding more environment variables

You can add and remove as many environment variables as you want. The previous section focuses only on the variables that are required for Gatsby Cloud to integrate with your CMS.

Webhooks: Configuring your Gatsby site to work with Gatsby Cloud

Setting up a webhook in Strapi

To make a connection between Strapi and Gatsby Cloud for your site, you’ll need to configure a webhook in Strapi so that content changes can be pushed to Gatsby Cloud.

You can add and edit necessary webhook information in two places in Gatsby Cloud:

  • During the “Create a new Site” process
  • After setting up an instance, on that instance’s Settings page

Strapi documentation on webhooks

Strapi - What is a webhook?

Adding a webhook

In “Create the instance” we created a Gatsby Cloud instance which exposed a webhook. We’ll use that exposed webhook now.

Navigate to your Gatsby Cloud instance, and press “Site Settings.” Copy the Webhook on this page.

Copying the webhook URL

Go to the Strapi admin and click Settings in the sidebar

Strapi admin with Settings sidebar link highlighted

In the Global Settings menu, select Webhooks

Strapi settings menu with Webhooks link highlighted

Click on Add new webhook

Image of add webhook button highlighted

Name your Gatsby Cloud webhook. Paste the webhook link you copied from the Gatsby Cloud dashboard. Select all events that you would like to trigger the webhook. image of webhook details page

Click Save to save these changes.

Your new webhook will now trigger a Gatsby Cloud Preview update any time you trigger any of the events you selected!

Wrapping Up

At this point, you now have a Strapi instance configured to best support Gatsby Cloud. Edit content and watch it appear live in Gatsby Cloud!

© 2020 Gatsby, Inc.