Headless WordPress

For step-by-step instructions on using WordPress as a headless back-end with Gatsby as the front-end see the GitHub repo

Interesting Note: We’ll be looking particularly at static site generators (SSGs) of which Matt Mullenweg is not a fan.

What is Headless?

  • Some confusion regarding terms due to inconsistent use within community (which tends to happen):
    • In a generic sense, “head” is the front-end (UI) of a site (do we actually use it that way?) so “headless” is a site without a front-end.
    • “Headless” sites have existed in the WordPress ecosystem using the REST API.
    • More recently, the term has been used in association with Static Site Generators (SSG’s) such as Gatsby, where WP serves as the back-end (“headless”) and Gatsby serves as the front-end (“head”).
    • While other languages (Go: Hugo, Ruby: Jekyll) provide SSG’s, the most popular are in JS and these are often referred to as using the Jamstack (JavaScript, API, Markdown).

Why Use Headless?

  • Performance Gains
  • Scalability
  • Reduced Cost (at scale)
  • Security Improvements
  • Decoupled UI
  • Use Latest JS Frameworks
  • Separation of Concerns (SoC)

Downsides of Headless

  • Now maintaining two separate sites – WP back-end and front-end.
  • The complexity of front-end frameworks (e.g. React) reduces productivity in the short-term.
  • Loss of plugin functionality (most WP plugins won’t work in a static environment).
  • Must be rebuilt every time a change occurs.
  • Takes a long time to build (depends).

WP Plugins for Generating Static Sites

WP Static Hosts


Learning More



  • WP Search? wp-search

Making an Easy Mistake with the gatsby-source-wordpress Plugin

Maybe no one is like me, but I’ve tripped over this same mistake several times now and hope I can spare you the trouble.

In order to configure Gatsby to work with WordPress you use a Gatsby (not WordPress) plugin called gatsby-source-wordpress. You can then write a GraphQL query to pull data from your WordPress site.

Try running gatsby develop and you may run into the same errors I encountered.

There was an error in your GraphQL query:
Cannot query field "allWordPressPost" on type "Query".

Generating development JavaScript bundle failed...
Cannot query field "allWordPressPost" on type "Query".

The likely reason Gatsby is throwing these errors is because you used allWordPressPost in your query instead of allWordpressPost. See the difference? In Gatsby you DON’T capitalize the letter p.

Its that simple…and yet that makes it all the more easy to overlook.