How to Build Headless WordPress Sites with Gatsby

So you’ve heard about Gatsby, but what is it really about? How does it work with WordPress?

We are old pros with WordPress, and we’ve recently been using Gatsby a lot. We love it, but there’s a bit of a learning curve. This article should help clear up any confusion, and get you started building headless (or decoupled) WordPress sites.

Table of Contents

  • What is Gatsby?
  • Why Gatsby + WordPress?
    • Advantages
    • GraphQL
    • Drawbacks and Hangups
    • What type of sites don’t work with Gatsby?
    • What about other frameworks?
    • Example sites
  • How to Get Started
    • Project Structure and Workflow
    • Step One: Setup Your WordPress Site
    • Step Two: Setup Gatsby (with video)
    • Step Three: Setup Gatsby Hosting

What is Gatsby?

Gatsby is a modern static site framework built on React. It can also use all the dynamic features of React, you are not limited to static content.

Gatsby works as the front-end of a WordPress site, you can think of it as replacing a theme. It does not live in a WordPress theme or plugin however, it is a separate app that pulls in WordPress data through an API.

Image from

Modern Javascript developers will feel at home using it, it’s very simple to install and run a local development environment. To deploy you run a build and put the static site files on a server.


Here are a few things I love about Gatsby.

  • Speed – It’s crazy fast, even on a cheap/free hosting account.
  • Security – Since we are outputting static HTML files, there’s nothing to hack.
  • Affordability – Serving static files is easy, so you get insane performance out of the box, and it’s more affordable to scale up.
  • Easy/Fun to work with – Gatsby abstracts away a lot of the hard stuff about a React app, like routing, image optimization, and more. It’s also really fun to work with.

Why Gatsby + WordPress?

Gatsby modernizes your WordPress site.

Many modern websites use a paradigm called JAMstack, which refers to Javascript, APIs, and Markup. This enables performance and flexibility that is critical for businesses with an online presence. It’s a big deal.

WordPress has a lot of advantages for content management, and it’s a familiar admin interface for both business owners and developers. It does not use JAMstack out of the box, that’s where Gatsby comes in.

Here are some advantages to a Gatsby + WordPress site:

  • A blazing fast mobile site with no AMP headaches.
  • WordPress relies on heavy caching, which causes tons of problems. Forget about caching plugins and settings, you don’t need them.
  • Pay less than $5/mo for hosting instead of $99/mo or more, and get better performance (that’s what we are doing with this site).
  • A decoupled front end is flexible. If you change or add data sources, or redo your backend architecture, your front-end only needs minor changes.
  • Integrate multiple services easily. For example, use WordPress for your posts and pages, markdown files for your documentation, Shopify for products, Google Sheets for data, and Zapier for integrations.

Building a React app from scratch involves a lot of hard choices and custom development. Gatsby handles much of this for you, helping you focus on the features and design instead of the infrastructure.


Gatsby uses GraphQL to handle data. It’s a new type of API that is spreading like wildfire because of it’s clear advantages over REST.

We won’t go into the specifics here, just know that it’s really fast and it’s worth learning. There is also a plugin for WordPress called WPGraphQL that we use to fetch all your posts and pages. It is superior to the WP REST API in speed and flexibility.

You can learn more about Gatsby and GraphQL here.

Drawbacks and Hangups

A Gatsby site does not translate 1 to 1 with a WordPress site, it is helpful to reframe your thinking. After all, you don’t get all the speed and scalability without a few trade-offs.

In WordPress, you can add a plugin like Gravity Forms, configure a few options, and it just works. A Gatsby site uses an API to get your data, so a Gravity Form will not work out of the box. In fact, most plugins won’t work out of the box.

Here are some things to consider:

  • Theme features or styling don’t work OTB.
  • Most plugins don’t work OTB.
  • Changes to the site take a few minutes to show up.

You have to start thinking about WordPress as a data source, not as the place for features/functionality.

What type of sites don’t work with Gatsby?

Right now, the best type of sites for Gatsby are content-centric, like a magazine, church, podcast, sports or news, or any business marketing site.

Something that wouldn’t work with Gatsby would be lots of private user data, such as the WordPress admin, or a banking app. Private data should not be static, so it doesn’t make sense to use Gatsby for something like a banking app. I also wouldn’t use Gatsby for a site that has 10,000+ products that are being updated often.

You can do things like protected member areas, eCommerce, and dynamic data with Gatsby, but it requires custom development. Things are happening fast, I expect that in the coming months and years Gatsby will be an easy choice for almost any type of site.

What about other frameworks?

There are lots of other ways to build JAMstack WordPress sites. You can use plain old Javascript, a framework like Vue or Next, or a static generator like Statamic or Jekyll.

These are all great options, but we like Gatsby. In our experience it is well suited for the types of sites we like to build, it uses well-supported technology like React, and a great community around it. On top of that, as a company Gatsby seems invested in the WordPress ecosystem.

Example Sites

What does a decoupled WordPress site using Gatsby look like? Here are a few examples.

Getting Started

Let’s build a Gatsby site powered by WordPress! First we need to understand the overall structure and workflow for this project.

Project Structure and Workflow

Headless WordPress with Gatsby

For a decoupled or headless WordPress site, you are using WordPress as one of potentially several data sources.

Here’s how that looks:

  • A WordPress site hosted somewhere live on the web.
  • An API for WordPress data, like the WP-API or GraphQL.
  • A Gatsby site hosted separately, pulling in WordPress data via the API.
  • A deploy process to rebuild your Gatsby site when data changes in WordPress.

Here’s an example of how we made this site,

  • WordPress installed at the wpgraphql plugin, and Gatsby Toolkit plugin active.
  • A Gatsby project using create-gatsby-theme-publisher, hosted on Github.
  • Free Netlify account hooked up to Github for

Let’s go over each of these steps in more depth.

Step One: Setup Your WordPress Site

The first thing we’ll configure is your WordPress site, which will be our data source.

You can use an existing site or create a new one.

A. WordPress Hosting

The easiest way to get started is to create a new WordPress installation on any host. It just needs to be publicly accessible, so you can use SpinupWP to create a site on any platform, buy a managed WordPress hosting plan, etc.

Since traffic will not be hitting this site directly, you do not need an expensive plan.

You can also move an existing site to Gatsby, but there are some extra considerations. You will have to change the domain for the site and all assets like images and links. There will be some downtime migrating the site.

B. Configure a domain

Next you’ll need to configure a domain for your WordPress site. We like to use a subdomain such as, but it’s not public facing so it doesn’t really matter.

That’s it for now, we’ll come back to the WordPress site later.

Step Two: Setup Gatsby

The best way to get started is with a theme.

We’ve used starters, plugins, themes, and everything else Gatsby has to offer, and it can get pretty confusing. Save yourself the trouble of trying to cobble this all together yourself and just use our free Publisher theme.

We put a lot of work into it so you can focus on customization, but if you choose to take a different approach feel free to skip this section.

Video Tutorial

A. Setup your local Gatsby project

Choose a folder on your computer for your local project, and clone or download the create-gatsby-theme-publisher repository, then install the dependencies.

git clone

cd create-gatsby-theme-publisher


You can change the folder name and the theme name in package.json if you like.

Open the theme folder in your favorite code editor, then open gatsby-config.js

Replace the site details with your own. The most important is the wordPressUrl setting, which tells Gatsby where your site is located.

Run gatsby develop in your terminal to fire up the site.

Congratulations, you officially have a Gatsby site running (locally)!

B. Customize

You can think of the theme you just created as a child theme of gatsby-theme-publisher. You can add files to it that will overwrite the main theme files, in Gatsby this is called shadowing.

This theme uses the latest React principles such as CSS in JS, along with the Chakra UI component library. We chose Chakra UI because it is based on the Tailwind CSS framework which we love, but it has all the features we needed in a React app.

If you are not used to writing your styling inside your components it takes some getting used to, but it allows for the most flexibility.


To customize the theme colors, visit your-theme/src/@staticfuse/gatsby-theme-publisher/theme/theme.js.

You will see some example customization commented out, uncomment and change the values as you like. For example:

const publisherTheme = {
  colors: {
    text: "#2D3748",
    primary: "#bada55",
    headings: "#bada55",
    links: "#bada55",

This theme uses the styled system theme specification, this allows you to define global variables that can be used in your components, such as colors, fonts, breakpoints, and more.

You will also find a style.css file which will load any static styles you’d like to add. This is not the recommended approach, but it’s there to make things easier. You should use styled components wherever possible for flexibility.


To add a custom logo, save a file called site-logo.png and overwrite the existing images/site-logo.png file. The new logo will automatically be used. If you need to adjust the styling, visit the theme/src/@staticfuse/gatsby-theme-publisher/components/Logo.js file and adjust the styling as needed.


You can customize any file in the theme, such as the main header or body layout, by adding the file to your theme’s components folder.

For example, to edit the header, add a file at theme/src/@staticfuse/gatsby-theme-publisher/components/Header.js. Copy the code from the main component into this file, and then edit as you like.

You can see all available components and their code on Github here.

Once you are done customizing, make sure your work is saved.

Step Three: Hosting and Deployment

You’ve made it through the hard stuff, congrats! The next steps are pretty simple.

A. Gatsby site to git

The first step is to create a new git repo and push your local Gatsby project there. Github is free and easy, but you can use any git host.

B. Setup Netlify (or another host)

Next you need to host your Gatsby site.

You can use any host, these are just HTML, CSS and Javascript files, so it doesn’t need much. We like Netlify because it’s free, they handle rebuilds in the cloud, and it’s super easy to setup.

Create a new account on Netlify, and add a new site from Git. Follow their instructions to connect your Github account and deploy your site.

Tip: run “gatsby build” locally before deploying to Netlify. That way you can fix any errors locally and avoid errors when deploying your site.

C. Connect your domain

If you’d like to add a custom domain, you can use a CNAME to point your domain’s www path to your Netlify subdomain. You can also use their DNS, which is very simple.

Here are Netlify’s instructions to connect your domain.

D. Setup a build hook

Gatsby turns your WordPress data into static files. That means that when you create or update a post, you need to re-generate the static files.

With Netlify, we can easily trigger a rebuild when a new post or page is created or updated.

We have created a free plugin that handles this for you. Install and activate the Gatsby Toolkit plugin to deploy to Netlify every time a new post is published or updated.

Create a new webhook on Netlify, by visiting the Build and Deploy => Continuous Deployment settings.

Click Add Build Hook, give it a name, and add it to the Gatsby Toolkit settings under Build Hook.

With that build hook added, Gatsby will grab your newest data every time you update or publish. Keep in mind this can take several minutes for large sites.

That’s it, you new have a headless WordPress site with Gatsby!

What is Static Fuse?

We made a short podcast talking about who we are and what Static Fuse is about.

Static Fuse is a collaboration between Justin Hall and Scott Bolinger. We were both working on Gatsby projects separately, and we decided to team up.

Our goal is to create resources that help other developers build headless sites with WordPress and Gatsby.


We are starting with the Publisher theme and a deploy plugin, along with educational resources. Going forward, we want to create other themes for different types of sites, and build out the Toolkit plugin with more features.

Beyond that we want to gather feedback to see what resources you are interested in.

We are learning a ton and we want to share with you, sign up for our email list to learn more about Gatsby and WordPress.