Gatsby Cloud Docs

Getting started with Gatsby Preview and Drupal

Learn how to connect Gatsby Preview with Drupal

Table of Contents

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

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

Automatic Integration

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

Adding the webhook to Drupal

To live-preview content from Drupal, you will need to do several things, specifically:

  1. Install the “Gatsby Live Preview” module
  2. Pass the Gatsby Cloud instance URL to the “Gatsby Live Preview” module

Doing each of these allows Gatsby Cloud to receive content updates from Drupal without refreshing or rebuilding. Excellent! Let’s get started.

Installing the “Gatsby Live Preview” module

In Drupal, modules can be installed in several ways.

If you know how to install modules through the command line, you can use Drush (drush en gatsby) or Composer (composer require drupal/gatsby).

If you’re unsure how to install modules, please proceed.

First, log on to your Drupal admin interface. Next, go to the “Extend” tab.

Extend Tab in Drupal Admin

This view will allow us to install community modules (“Gatsby Live Preview” in this case).

Press the “Install new module” button and we’ll use the “Install from a URL” method.

Install Gatsby Live Preview Module

At the time of this writing, the URL is, but please check the “Gatsby Live Preview” project for the latest version.

Installing this module will also install the JSON:API module if you haven’t already installed the JSON:API module.

Finally, to install, we’ll select the “Gatsby Live Preview” module in our Extend view and press the “Install” button.

Press install to install gatsby live preview module

Configure “Gatsby Live Preview” module

In “Create the instance” we created a Gatsby Cloud instance which exposes a preview URL. We’ll use that URL now. Let’s add this URL to our “Gatsby Live Preview” module.

In the “Extend” tab, tap “Help” on the “Gatsby Live Preview” module.

Tap Help on Gatsby Live Preview

Tap “Gatsby Live Preview Settings”, paste the Preview URL, and tap “Save configuration.”

Configure Gatsby Live Preview

Note: We only need the base URL instance here, not the webhook URL.

Setting up Environment Variables

If you have enabled authentication for your Drupal instance, you will want to add any necessary environment variables (e.g. DRUPAL_USERNAME, DRUPAL_PASSWORD, etc.) so that Gatsby Preview can expose these variables to your application.

Wrapping Up

At this point, we now have a Drupal instance configured to best support Gatsby Preview. Edit content, and watch it appear live in Gatsby Preview!