Brian Bancroft

Wordpress and Gatsby for People who Seldom Touch Wordpress

September 07,'19 | Tutorial
Gatsby Source Wordpress image

A couple months ago I was delighted to learn on that Jason Bahl, a senior Wordpress developer, was picked up by Gatsby to lead the integration between Wordpress (one of the world's most popular CMS/Blogging Platforms) and Gatsby (an up-and-comping React-centric Static Site generator). This project is still in progress, and has manifested in two wonderful tools still in a pre-publish state:

  • wp-grapql

  • gatsby-source-wordpress

The "wp-graphql" plugin allows Wordpress sites to expose a GraphQL API endpoint with minimal configuration, where the Gatsby configuration "gatsby-source-wordpress" allows your app to seamlessly consume what comes out of the Wordpress site's graphql endpoint.

This post aims to show casual Wordpress users how to set up both integrations so that they can access the Wordpress site's data from the Gatsby GraphiQL interface. From there, they will be able to build pages similar to how they would do so in other workflows such as local markdown, or headless CMS platforms such as Contentful.

Configuring Wordpress

Start by creating a Wordpress app, or just by having one. There are many ways to build Wordpress locally, but if you're not familiar, it might be easier just to make a Wordpress app using or another hosting solution such as GoDaddy or Bluehost. The later two cost money, but the benefit is that you don't have to spend a lot of time figuring out how to build a WP app locally on your machine.

Get a Plugin

Once you've built a Wordpress application, you can add the plugin. The easiest place to find the plugin is one the releases page of the plugin's Github repository.


Find the newest version on the releases page, and click on the link to the changelist. Once there, you can find the zipfiles at the bottom of the page. Download the source in .zip.

warning: This is still in pre-release, which means the endpoints aren't stable

Configure the Plugin

Once you've downloaded the plugin, you can follow the directions on this site:

I personally activate the plugin via the GUI. Go to the "Plugins" page (you can find it in the left-hand menu of the admin panel. Then in Plugins, click on "Add New", and add the zipfile which you just downloaded.

Wordpress Plugin Page

Publish the Site

Once you've added the plugin, you should verify whether the site's been published. If not, you should publish it. Unfortunately, there are many ways to do this. If you're not sure how to do it at this time, prepare to bang together some stones.

Write a Post

Last but not least, you need content! Create a post. Add an image. Hit publish. It doesn't have to be much, but something has to be there to test against

Sample Wp Post

Okay... At this point, you've built a basic Wordpress site which you can draw content from. If you are able to see the posts from an incognito tab, then you'll be able to proceed with the following steps.

Configuring Gatsby

In this section, you'll build a new Gatsby app, and run it. You're going to need the latest LTS version of NodeJS, as well as some knowledge in command line operations, Javascript and GatsbyJS.

From the command line, you can create new applications using npx, a NPM tool that allows you to use any Node general-usage CLI libraries without installing them first.

npx gatsby new wp-graphql-sample

Once the application is installed, you will now want to install the Gatsby Wordpress plugin.

npm i gatsby-source-wordpress dotenv

As a common practice, you also will want to configure .env files so that if you're sharing your code, you'll be to be able to hide secret information from the general public. So at the top of gatsby-config.js, you'll want to add the following line:


Once you've added this line, you'll be able to use .env variables, and set the plugin. In the .env file, I've added something similar to You should do something similar without trailing slashes or the proceeding http/https. Here's the plugin config:

resolve: `gatsby-source-wordpress`,
options: {
* The base URL of the WordPress site without the trailingslash and the protocol. This is required.
* Example : '' or ''
baseUrl: process.env.WP_SITE,
protocol: `https`,
// Indicates whether the site is hosted on
// If false, then the assumption is made that the site is self hosted.
// If true, then the plugin will source its content on using the JSON REST API V2.
// If your site is hosted on, then set this to false.
hostingWPCOM: false,
// If useACF is true, then the source plugin will try to import the WordPress ACF Plugin contents.
// This feature is untested for sites hosted on
useACF: true,

With this, you should be ready to launch the Gatsby development server. Don't be alarmed if your page is recently published _and_ you're still seeing a lot of unauthorized (403 or 401) errors in the CLI during the build process. We're only interested in posts at this time. However, if you're prevented from seeing the posts at all once you've started, you should look at the plugin page's instructions for further direction.

Testing the Integration through GraphiQL

In GraphiQL (normally http://localhost:8000/___graphql), you should be seeing your familiar Gatsby testing interface. Here is a sample posts to get started:

query getAllPosts {
allWordpressPost {
edges {
node {

Once you've started here, you can move to getting single posts, and content:

query getSinglePost {
wordpressPost(id: {eq: "5ffd2619-230b-517f-9223-41d943012a4b"}) {

With luck, you should see something like the following:


At this point, you've proven that you can access Wordpress content through your Gatsby Application. The next steps would involve building index and post pages through Gatsby. this will require some transformation and other work. To dive further, you should consult the Gatsby Source Wordpress documentation.

3,2,1... You're Done!

This is an interesting project, but remember that this is in pre-release. This means that the way parts of this interact are very likely to change over the next year. You should not use this on production sites and expect the way it works to remain the same through version 1. Still, I am excited for the prospect of using GraphQL to connect a Gatsby Blog to an existing Wordpress site, and I'm especially happy with how little effort it took me to put one together.