What is headless WordPress - an in-depth comparison

Ah WordPress, the Content Management System that powers over 40% of the web. I think it's fair to say there is a big market for it. Now over the past few years, it seems something else has started to take the web dev scene by storm, JAMstack. This has lead to a new way of building the web of the future, and even WordPress is invited along for the ride!

But it's not WordPress quite as you know it, oh no, this is headless WordPress.

What is headless WordPress?

This is the principle of using WordPress with a decoupled frontend, where content is queried via an API such as REST or GraphQL (WPGraphQL), then displayed on the frontend.

Why might you want to use WordPress as a headless CMS?

The tech industry is moving at a phenomenal speed, and more specifically, websites and apps built with JavaScript-powered libraries and frameworks are starting to become the norm. Now then, WordPress was created way back in 2003, built on PHP. The platform has come along way, and it too has adopted some of this modern tech, with its Gutenberg block builder using React. However, you still remain within the confinement of a PHP based frontend.

Now that we understand what headless WordPress is, we should quickly remind ourselves how a traditional WP frontend works. This will help us draw up a comparison at the end!

The traditional way

If you've ever built a WordPress site, there's a good chance it was built traditionally, where all the code you write is in a theme. The theme controls what happens on both the backend and the frontend, it's where you'll have all your page templates, CSS and JavaScript.

Now we're not going to go in-depth on exactly what the setup of a WP theme is, as that's out of the scope of this post. You can find out more about themes over on the official WordPress Theme Handbook.

There are many many ways of working with a theme, you could be using a pre-built theme with lots of templates to choose from, that probably uses a page builder like Elementor. Or you could be building a custom theme that is bespoke to the needs of a project. Whatever the case, the fundamental structure is always the same, and therein lies the problem for many.

The headless way

Using WordPress as a headless platform does away with following the 'rules' of WordPress theme development. Long gone are the days of using the likes of a header.php, footer.php and style.css. You are free to structure the site however you please, which allows for a more tailored project, opening possibilities not previously available to a WordPress site.

Now before you get too excited and hit that ctrl + alt + del on a theme, WordPress still actually needs a theme in order to function. And your swanky new headless frontend may require some custom backend logic, or modify the WP admin to some degree.

So you could either use a default theme, Twenty Twenty One, or you could create your own barebones theme starting out with only the necessary file. I find it easier to have a barebones theme setup rather than using a default theme, as for one, you're not going to be making any use of 90% of the features of the theme, and two, you'd have to make a child theme for any custom bits anyway.

An example of something that you will still need the theme for is to register menu locations and custom post types. These items are backend logic and should be done the same way as if you were building a traditional site. Anything that is backend logic, you probably won't need to change how you work with, unless said logic needs to expose some data to the frontend that won't be handled by an existing mechanism.

So, now that we have a grasp on the idea of a headless frontend, and we refreshed our brains on the traditional way with themes, let's put the two head-to-head.

Comparison time

Pros of headless WordPress

• Full control over the technology used on the frontend, from React to Vue to Angular. This factor alone is game changing to many, allowing endless possibilities for how the frontend is created. For example, if you only wanted a simple blog site, you may be best using an SSG like Eleventy or Gatsby. Whereas if you're working on a large commerce site, Next.js would be a better fit for scalability. This control over tech stack used all ties into the Developer Experience, which I always believe plays a massive influence in the success of any project.
• Enhanced security by going headless allows your frontend to be hosted away from the WordPress installation. This is great for many many reasons, like someone can't just do example.com/wp-admin as the frontend isn't within a WordPress installation. It also protects against the likes of DDoS attacks.
• Hide the CMS source completely, something that is theoretically possible, dependant on your setup. Providing you don't make any client-side API calls directly to the CMS, and if you alter the directory structure to images, it is plausible to totally mask the fact you're using WordPress or any CMS for that matter. This could be very welcoming news to those always looking to improve security.

Cons of headless WordPress

• Reduced extendability. WordPress is well known for it's large eco-system of plugins, which allow you to easily extend the functionality of your website in one way or another. However when you go headless, many of these plugins will seise to work as intended. The reason being, these plugins are only built to work with traditional WP, whereby any frontend code is 'hooked' onto frontend template actions. So with headless, the actions are never run as they are never called as there are no PHP page templates. For example let's take Yoast SEO, one of the biggest plugins out there. Now all the meta data Yoast outputs to a page <head> is done so through the wp_head action. As this is the only means of outputting any meta data Yoast understands, we turn out attention to fix that. Now it is possible via WPGraphQL, using add-on plugins to expose a plugins data to the API, for us to query on the frontend. Luckily, there is an add-on plugin to Yoast SEO which allows just this. This is only one example, not all plugins have dedicated add-ons to extend to the GraphQL API.
• Forces an alternative hosting setup. With a traditional site, the frontend and backend exist coupled together in a single place on a server. So when you go headless, you can't have the frontend inside the WP installation. Instead, top recommendations are to use a dedicated hosting platform for these types of websites. Welcome the likes of Netlify or Vercel. These have super simple setups to get a project up and running, taking care of of pretty much everything including free SSL's. You are free to host the WP installation wherever you please. This one isn't as much of a big deal, but still something you should be aware of as both Netlify and Vercel are paid if you want to use commercially.

From this in-depth look into the pros and cons of headless WordPress, it's important to make sure you're aware of what you're getting yourself, your team and maybe your client into. As, failure to clearly outline what headless means for a project, could leave you in a sticky situation.

To conclude, is headless the way to go? In my book, yes, most definitely. I believe the pros far out way the cons, in terms of both the possibilities it opens and future-proofing. As mentioned above, it is so important to make it clear to those it will affect, that a site is headless. Failure to communicate this could be devastating. Your manager or the client may know you're building a WordPress site and think that's great, and look forward to extending the site with various plugins etc... Little would they know that a headless site takes away much of this extensibility. On the flip side, if this isn't an issue and everyone is on the same page and understands the benefit of going headless, then you're onto a winner!