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
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.
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 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.
Once the branch and base directory are correct, select “Next.”
Create the instance
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:
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
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.jsfile at the root of the site - If you don’t have a
gatsby-config.jsfile, create one
gatsby-config.jsfile, check that your
gatsby-source-strapiconfig contains the
It should look something like this:
apiURL: process.env.API_URL || "http://localhost:1337",
// List of the Content Types you want to be able to request from Gatsby.
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
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.
Go to the Strapi admin and click
Settings in the sidebar
Global Settings menu, select
Add new webhook
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.
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!
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!