Headless WordPress with React & Gatsby - Part 1: Choosing our tools

Photo of Nick Bishop Written by Nick Bishop,   May 31, 2018

Web development is accelerating at an incredible rate - new frameworks seem to pop up every day. Whilst this is exciting (at least to a front-end geek like me!), it can be difficult knowing which new tools are any good and which ones you should be using.

As a business that specialises in content management, one area of web development that’s been hard to ignore is the rise of headless or decoupled Content Management System (CMS) architectures and the tools surrounding these.

The benefits of Headless CMS are well-documented:

  • CMS agnostic front-end - lets you pull content from wherever, and present it in whatever way you choose
  • Ability to utilise the latest front-end technology - e.g. Full-stack React, Vue rather than battling the CMS's own templating solution
  • More control over performance - lets you control your own asset / build pipeline, rather than having the CMS do it
  • Abstracted content facilitates multi-channel delivery - lets you consume structured content through APIs

A couple of months ago, we decided to put our money where our mouth is and use it on one of our client projects, Fudgelearn. To make things even more interesting, we only had a few weeks to turn it around.

Here’s what we learnt...


Choosing a Content Management System


There are tons of content management systems out there. You get the traditional open source ones (WordPress and Drupal), and the enterprise offerings from the likes of Oracle and Adobe. There are also a plethora of cloud-based upstarts, looking to capitalise in the headless area by eschewing some of the bloat that the more established CMSs have picked up over the years - Contentful & Prismic to name just a few.

So which one do you choose?

The key to headless is being able to consume content using a structured API, e.g. REST or GraphQL. All the above CMSs offer APIs, with varying features and different degrees of ease-of-use. The enterprise solutions tend to provide extensive APIs; and the cloud solutions which were built API-first, are lean and specifically targeted at the headless / multi-channel use-case. On the open source side - Drupal introduced their RESTful Web Services API in Drupal 8, whereas WordPress has had a JSON REST API (WP API) for a while now.

Given that our content requirements were initially quite basic (i.e. static content, few content types, no authentication), and we wanted flexibility in terms of hosting the CMS, we decided to go with WordPress. The WP API is mature and easy to use, the plugin system provides a good level of extensibility, and WordPress installations are generally quite portable. Not to mention the fact that WordPress itself is extremely easy and intuitive for content managers to use.


Choosing a presentation layer


Our UI team are big fans of React - encapsulated components and a superb state model make it extremely easy to build performant UIs. You can also render React on the server, and use it to build native mobile apps. React was a simple decision for us.

At this point, we still had to decide on the rest of the presentation framework - specifically, how we intended to consume content from WordPress, and deliver our website. As we mentioned earlier, React is an extremely flexible library, and lets you use a variety of approaches for website delivery - client-rendered / single-page application (SPA), server-rendered, statically-rendered (pre-rendered) or a hybrid approach.

Whilst a client-rendered / SPA approach is potentially easier (because it doesn't need additional tooling), it still seems like it's beneficial to have a server, or statically rendered version of your site, to reach peak performance and satisfy some crawlers, e.g. Facebook. With this in mind, we started looking at server and statically rendered approaches. Given that we’d already offloaded the hosting of WordPress to WPEngine, we felt that we didn’t really want to be provisioning web servers / middleware ourselves, either.


It turns out that you can do server-side rendering (SSR) without having to worry about writing your own Express servers (or getting bogged down in streams and content hydration). A number of tools have popped up recently that make this process a cinch - special mention here goes to Next.js, which is both a minimalistic and intuitive framework. Many of these tools offer server provisioning as part of the package e.g. Next.js + Now, enabling you to go 'serverless' at little cost. Whilst this approach was attractive, we questioned whether server-side rendering was necessary for a site that didn’t have much in the way of dynamic content (at least initially). We wanted to consider other options that might enable us to seek out a little more performance gain.

Static-site generation

Throughout the evaluation process, we found that there was a tool that kept popping up - Gatsby. Gatsby is billed as 'Blazing-fast static site generator for React'. Whilst there are a number of tools for generating static sites (including Next.js), Gatsby also offers a number of plugins for consuming content (including WordPress, Drupal & Contentful) out-of-the-box.

On top of this, Gatsby provides a powerful abstraction layer for querying this content at build time, by generating a GraphQL API. Harnessing content within React becomes a breeze. Throw in the fact that Gatsby is highly tuned for performance, offers code and data splitting out-of-the-box, and you have one impressive tool.

With Gatsby, our tools were prepped and we were ready to start building...

Look out for Part 2 where we'll talk about how we tuned WordPress for headless content delivery.

We’d love to hear your opinion on this post