Headless WordPress has been gaining more and more interest from developers and hosting companies alike, especially over the last few months. With WP Engine launching their Atlas hosting and more and more developers preferring Javascript frameworks to power the frontend of their sites, headless WordPress seems to offer the best of both worlds: a familiar editorial experience on the backend with the flexibility to pick a modern tech stack on the frontend.
However, for all the benefits of headless WordPress, there are definitely some drawbacks as well. Not every hosting environment is set up to handle headless WordPress natively, so if you’re used to a more traditional WordPress setup, you may have to get creative with your hosting.
In addition, because the frontend and backend are separated, some of the pieces of WordPress that are normally included need to be recreated or at the very least reimagined.
In this article, we’ll take a look at some of the use cases where headless WordPress really shines as well as some of the situations where you may want to stick with a more traditional WordPress setup. And in the end, hopefully give you a better idea as to whether headless WordPress is a good option for your next project. Let’s dive in.
What is Headless WordPress
Whereas a traditional WordPress setup runs on a server that both provides the backend for editors and content creators as well as serves up the template and everything else to make the website look good on the frontend, headless WordPress is a term used to describe when the frontend and the backend that makes up a WordPress site are separated.
This means that, while the traditional WordPress backend experience is the same, WordPress is not responsible for serving up any template or theme-related content.
In a headless setup, WordPress outputs all the content of the site through API endpoints (usually either the WordPress REST API or WP GraphQL). These API endpoints are consumed by a separate frontend that’s entirely responsible for handling the display of the content.
In many cases, this is a site put together with one of the popular Javascript frameworks, a mobile app, a conversation application powered by Alexa or Google Home or almost any interface that can consume content via API. Take a look at the WPCasts video below to see what that could look like.
This makes a headless WordPress site much more flexible in terms of how the content can be presented. With a traditional WordPress setup, you are largely locked into the output that’s controlled by the theme, but with headless, you can output the same content and have it presented to your end users in many different ways because the presentation is controlled by the platform that ultimately consumes the API endpoints.
Benefits of Headless WordPress
Headless WordPress continues to grow in popularity because for some developer and content teams, there are definitely some strong benefits to a headless setup.
Different teams can do what they do best
Some organizations, even software businesses who employ developers, find that while the marketing department wants to use WordPress for the marketing site, it doesn’t overlap with the skillset of their existing developers and they end up outsourcing this work to an agency or a freelancer who is more WordPress-centric.
However, with a headless WordPress setup, internal developers can choose to use whatever frontend framework they like to develop the frontend of the site, leveraging their existing skills even if they have no experience with WordPress.
The WordPress-specific work can then be outsourced and connected with the in-house frontend via API, potentially saving on cost to develop the site as well as allowing all the brand and company-specific knowledge that’s in-house to come through on the frontend of the site where there might be something lost in translation otherwise.
Editorial can use the WordPress they’re familiar with
If you have an editorial team or content creators that are already familiar with the WordPress editing experience (which is more and more common as WordPress takes over even more market share), you don’t have to decide between letting your frontend keep up to date with the very latest technologies and giving the content creation team an experience they’re familiar with.
By using a headless WordPress setup, the content creators can continue to produce content in the WordPress experience they’re familiar with, while the development team is free to use whatever frontend technologies they’re most comfortable with.
Backend APIs can power different platforms
When working with a headless setup where WordPress is powering API endpoints instead of simply serving up frontend templates, you have the flexibility to have these endpoints push content to interfaces other than just a website.
The same API endpoints that output your content to the web can also power mobile applications, interface with another CMS that powers a print publication, be the content provider for a voice application with Alexa or Google Home and much more.
Because so many interfaces are set up to consume APIs, using WordPress as a headless application really broadens the possibilities for where you can use and reuse the content you’re already writing in WordPress.
Drawbacks of Headless WordPress
While there are some benefits to a headless WordPress setup, it’s definitely not for everyone. If you are used to a more traditional WordPress experience and don’t fit any of the situations above, here are some of the potential drawbacks you’ll want to consider before jumping in.
Plugins don’t always work
Most people have the impression of WordPress and the WordPress ecosystem that if you need additional functionality for your site, you can go looking for a plugin that provides that functionality, install it and “it just works”, often without any code or configuration necessary.
However, with a headless WordPress setup, many plugins don’t work out of the box, as they aren’t necessarily aware that they have to provide their functionality via API. For some plugins, that sort of behavior isn’t even possible.
Take, for example, a plugin that adds social share links to the top of the single post page to make content more easily shareable across the various social networks. With a normal WordPress installation, this plugin could be activated and the social share icons could be easily injected automatically or using a shortcode or something and you would be all set.
However, with a headless setup, these social icons aren’t transmitted through the API output, because they don’t exist in the post content. And even if they were somehow added to the output of the API endpoint for a particular post, they wouldn’t show up on the frontend of the site unless the frontend was specifically built to look for that output and display the buttons. While not impossible, this makes many WordPress plugins more time consuming to implement in a headless setup.
WordPress-familiar teams don’t always “get” headless
If your developers or development team is already familiar with a more traditional WordPress setup, where display logic exists in the theme and most customizations are made to theme files, shifting that mindset to work with a headless setup can sometimes be difficult.
Even from a development process perspective, a headless setup sometimes requires a shift in how version control is used, how automated deployments and hosting are set up and handled, and increases the need for communication, especially if two different developers or teams are working on the frontend and backend pieces of the site. All of these things are tasks that developers used to working all together in a more standard WordPress theme may have never had to deal with before.
Debugging can become more difficult
Any system, whether it’s distributed or more of a monolith, can have bugs that come up during the course of operation. One of the challenges with distributed systems, however, is there’s so much more data and so many more choices you have to make when trying to debug an issue. For example, with a headless WordPress setup, if you experience an issue with posts not loading in the order you would expect.
To even get started debugging this issue, you would first need to decide whether the issue was with the front end portion of the site or with the backend. As these are likely hosted two separate places, you would need to then find the correct log file for the system where you thought the bug was originating.
If there was a problem on the backend, for example, where it was not providing the correct posts through the API endpoint. If you were debugging a normal WordPress site, you might try to echo or var_dump some debugging information and then see how that information comes out on the front end as you debug.
However, with a headless setup, this information won’t appear in your template, but rather your API endpoints. And depending on how your API endpoints are configured, this sort of debugging might not work at all.
Especially if the work of maintaining the front end of the site and the backend of the site is split between two different teams, debugging a headless WordPress setup is generally more difficult and involves more communication that a more traditional WordPress site. Especially if you’re not as experienced with debugging distributed systems, this can be a a good reason to prefer a more straightforward setup.
WYSIWYG is more difficult
One of the key promises of the Block Editor in WordPress it that it moves your WordPress experience much closer to one of the ideals of many CMS platforms – providing a “What you see is what you get” experience as content moves from the editor to the frontend of the site.
However, on WordPress sites where the block styling in the editor is in a separate codebase from the front end display, it ends up being a bit more difficult to keep these components in sync. When any changes are made in the frontend codebase, those changes need to also be communicated and reflected in the editor styles to keep that consisent WYSIWYG experience.
As with some of our other downsides of headless WordPress noted above, this just means that more communication and organization is necessary to keep the two codebases in sync and providing the best experience for both the content creators using the backend, but also the end users experiencing the frontend of the site.
So which is better?
If you’ve gotten this far you can probably anticipate this answer, but whether or not you should use headless WordPress for your next site project really depends on you, the team that’s working on it, how the project is deployed and many other factors.
If you have a strong frontend team that’s comfortable interfacing with APIs and is used to communicating changes and working with more distributed systems, then it might make sense for them to focus on the frontend of the site while a separate team works on the actual WordPress piece.
However, if you’re more of a solo freelancer or don’t have a lot of experience in more distributed systems, version control, deployment, etc, it might make sense to stick with a more traditional WordPress setup.
Headless WordPress can be a powerful paradigm that allows you to leverage modern technologies and bridge the gap between an editorial experience that content creators are familiar with, while still being able to use some newer tech that hasn’t come to the WordPress ecosystem yet.
And as the developer tooling around headless WordPress continues to get better with headless-specific hosting and other tools designed to make developing in a headless setup easier, it will only become more accessible for more developers and brands.
In short, headless WordPress is here to stay and, if used correctly, can be a great tool in your toolbox as you build your next WordPress site.
