Connecting to WordPress – Gatsby

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

You will:

Create a website using data from WordPress.
Store its source code on GitHub.
Register this GitHub repository in Gatsby Cloud.
Configure WordPress webhooks to notify Gatsby Cloud about the content changes in preview and production.
Configure preview URLs in WordPress.

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

WordPress is the world’s most popular CMS. By integrating Gatsby with WordPress content editors can continue to edit and publish content, while developers build and ship the site using Gatsby. Gatsby Cloud allows you to integrate your site with WordPress in order to run performant builds and preview content changes made in the CMS before publishing.

Setting up a WordPress and Gatsby site

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

You will need a publicly hosted WordPress instance, you can find some info on choosing a hosting provider in the source docs.

Finally, you will need to install several WordPress plugins to source data out of WordPress. Install these from the source code:

WPGraphQL (Required) - [Repo]
WPGatsby (Required) - [Repo] [WP Plugin]
Other WPGraphQL Extensions (Optional) - If you use WordPress plugins like Advanced Custom Fields or WooCommerce you will need a WPGraphQL extension to source data from them. If one does not exist you can checkout the WPGraphQL docs for information on creating your own plugin.

For more info on these WordPress plugins checkout the docs.

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

Manual Setup

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

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

Environment variables are used to uniquely set values at run time. You can add optional environment variables in Gatsby Cloud to enable your instance to pull source data from WordPress.

The WordPress source plugin does not require any Environment Variables by default. This is because most data available from WPGraphQL is available without authentication. However, There are some cases you may need environment variables. These include but are not limited to:

gatsby-source-wordpress does support Basic Authentication. If you have chosen to secure your WordPress instance with Basic Auth, you will need to populate the environment variables for these credentials as you have configured them. e.g.:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-wordpress`,
      options: {
        url: process.env.WPGRAPHQL_URL || `https://your.fallback.url/graphql`,
      },
    },
  ],
};

If you use different WP urls in dev vs production you may need to set the Environment Variable for accessing the correct WP instance. e.g.:

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-wordpress`,
      options: {
        url: process.env.WPGRAPHQL_URL || `https://your.fallback.url/graphql`,
      },
    },
  ],
};

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.

Gatsby Cloud: Integrating your Gatsby site to be updated with content changes

To connect WordPress with your Gatsby Cloud instance, you’ll need to configure WPGatsby plugin so that content changes can be pushed to Gatsby Cloud.

You’ll add two webhooks in the WordPress plugin WPGatsby to trigger updates on content changes. You’ll also be configuring WordPress to use your Gatsby Preview domain for seamless previews of your gatsby site.

Click Save.

Your Gatsby Cloud integration is now complete! When you publish/unpublish content in WordPress, your Gatsby Builds will update and Preview will be availablle!

Wrapping Up

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