Headless WordPress

What is a headless WordPress?

It’s WordPress without the PHP theme. Instead of querying data in templates, you use API to fetch content. Similar to other headless CMSes you can use whatever front-end you want. Without the need to learn or even touch PHP. It’s also simpler to maintain and keep safe. If you consume content during the build or first render, you don’t need to deal with traffic spikes or issues with performance and uptime.

Often the main reason to decouple CMS from the frontend is the will to freely use modern frameworks like Next.js or Gatsby. With those tools come multiple benefits, from a better developer experience to a great UX that gives modern JS frameworks like React and Vue.

REST API or GraphQL?

Every site running WordPress since version 4.7, which has been published in late 2016, is a headless CMS by default unless you’ve disabled it. The REST API endpoint in WordPress started as a plugin and eventually, it moved into core.

It’s pretty powerful and you can manage every part of the WordPress website, from posts, pages to menus and WP settings. The issue is, that often in real-world projects you need all of this data all at once. It might be quite a waste of resources to make requests for all of those endpoints on every single page request or during static pre-building.

Here comes the WPGraphQL plugin.

The plugin enables a graphql endpoint to fetch exactly the data you need with one single request. It integrates with some of the most popular plugins like Advanced Custom Fields or Yoast. Similar to REST API, WPGraphQL offers an easy way to extend existing queries or create new ones.

WordPress Headless Plugins

The headless WP community is bigger than ever. The plugins are hitting stable, production releases and are used by more and more developers. Just take a look at the most popular WP plugins.

Yoast SEO

Last year, Yoast announced even better Yoast REST API endpoint. It integrates with WPGraphQL too thanks to plugin created by Ash Hitchcock. It’s not an official integration, but works really well.

Advanced Custom Fields

ACF integrates with both REST API and GraphQL. If implemented properly you can create a very structured and powerful content models. You can create reusable components that will be available in different post/page templates. Editors can easily create landing pages and posts. Then you can fetch that data using GraphQL fragments, like this:

{
  post(id: "acf-example-test", idType: URI) {
    acfDocs {
      flexibleContent {
        __typename
        ... on Post_Acfdocs_FlexibleContent_LayoutOne {
          text
          anotherTextField
        }
        ... on Post_Acfdocs_FlexibleContent_LayoutTwo {
          image {
            id
            sourceUrl(size: MEDIUM)
          }
        }
        ... on Post_Acfdocs_FlexibleContent_LayoutThree {
          gallery {
            id
            sourceUrl(size: MEDIUM)
          }
        }
      }
    }
  }
}

Extending the API

There are WordPress filters, hooks, and actions available if you want to customize or build new functionality into your site. Or better yet develop it as a plugin and release it on WordPress.org or publish it on GitHub. You can check out a list of WPGraphQL extensions here.

Ecosystem

It’s not just about the plugins. Many tools and companies start to see an opportunity in the headless WP movement. There is a great integration with Gatsby via gatsby-source-wordpress. It’s been downloaded almost 1 million times already and it’s growing.

WPengine works on their own headless solutions, check out Atlas which helps with managing headless WP instances.

What do clients say?

We have had an opportunity to work on a bunch of Headless WordPress projects. One of them we/ve featured on our blog. Check out the Backlinko case study. After a few years of monolithic infrastructure, they decided to move to Next.js and headless WordPress. The website is now 3 times faster.

We struggled with Backlinko’s loading speed for years. Due to large, high-res images and illustrations, our page sizes were enormous. And despite optimizing our WordPress theme as much as possible, our load times were still slow.

We decided to work with Bejamas to help move us over to Next.js. The move made a tremendous difference in our load times and Core Web Vitals scores.

Conclusion

While WordPress might be the most popular solution for businesses, downsides can be overwhelming. For example, we’ve recently researched 20K websites for speed and performance and found that 79.3% of WordPress run websites have a poor or slightly above poor Lighthouse performance score ie 0-50. With Google pushing for speed as an important ranking factor this may become a problem for businesses.

From a business standpoint, headless WordPress is a great solution if you already use WP. If you (and editors!) like its design and feel, just give it a try!

Headless WordPress Pros and Cons