WordPress is a powerful content management system thanks to its ecosystem of plugins, themes, and other resources.
One way to make it even more powerful is by going headless. With this architecture, your website’s content database is decoupled from your website’s display, providing more flexibility, easier multi-channel distribution, and faster performance.
In this guide, we'll cover everything you need to know about headless WordPress, and include insights from Ivan Popov’s session ”How headless WordPress benefits enterprises?” at WordCamp Europe 2022. Feel free to click on any of the links below to skip to that section:
- what it means for WordPress to be headless
- benefits of a headless WordPress configuration
- drawbacks of a headless WordPress configuration
- how to set up a headless WordPress website
What is headless WordPress?
To understand what makes a headless WordPress configuration different from traditional WordPress, we first need to talk about headless content management systems in general.
Most CMSs you’ve likely worked with are meant to handle both the front end of the website — the interface that visitors interact with, such as a web page — and the back end of the website — the files stored on servers, including scripts and a content database. The back end is where you create, organize, and manage the content before publishing it to the front end.
We can refer to this setup as a “coupled” CMS architecture, since the front-end editing tools and back-end management tools are on the same installation. Both the front and back end access the database and, together, produce the web pages and other assets that visitors request. Since a coupled architecture lets website owners manage their entire website from inside one intuitive program (such as WordPress), this setup is popular with beginners.
A headless CMS works differently: It removes the front-end tools, leaving only the back-end content management tools. Essentially, you’re separating the “head” (the front end) of your website from the rest of its “body” (the back end).
Headless CMSs still allow you to upload, create, edit, and organize content. But, instead of pushing content directly to the front end, a headless CMS makes its resources available to a separate front-end solution through a REST API. It doesn’t concern itself at all with how the content looks to visitors.With this set up, the database is only being accessed by the back end of the installation.
Here’s where headless WordPress comes in: The WordPress you and I know uses a coupled architecture. You manage your website’s assets in the dashboard and control its appearance through themes and plugins.
But, by sharing content via the WordPress REST API, any WordPress installation can be made headless. In a headless WordPress configuration, the content management tools are still available, but front-end features like themes and the block editor are not. Another front-end application handles how your WordPress website actually looks.
A headless setup isn’t the best solution for all WordPress users. However, there are times when this configuration is ideal. Next, let’s discuss why a business might want to try headless WordPress.
Benefits of Headless WordPress
Why would anyone forgo the convenience of traditional WordPress for headless? In some cases, a headless setup may be better suited for a business website than a typical WordPress installation. Here are some key reasons why:
Traditional WordPress renders web pages dynamically. This means that, instead of storing static HTML pages to send to users when requested, the hosting server constructs an HTML page each time a request comes in. That requires the server to run PHP and MySQL processes to fetch all the necessary resources from the database, assemble them into a page, then send this page to a user.
"This needs to happen for every website visitor, which puts more and more load on your server," Ivan Popov, the CEO of the agency Vipe Studio, explained in his WCEU session. This can lead to slow page load times, which hurt the user experience and reduce conversions.
By leaving the front-end delivery up to a separate application like npm or next.js, you can speed up your site. With these applications, almost no scripting is required when visitors come to your site, according to Popov.
That's because they fetch content from the database and assemble it into pre-rendered HTML pages, then ship those to clients upon request.
While there are simpler things you can do to improve performance in a standard WordPress installation, enterprise sites with lots of traffic will hugely benefit from the faster speeds that headless WordPress provides.
"The value of headless WordPress comes when the website is big," Popov stressed. So publishers and other enterprise sites that get millions of visitors a month should consider making this investment.
WordPress allows you to do a lot with the front end, with its huge selection of customizable themes and plugins. Still, not everyone may want to control their website front end this way.
With a headless CMS, you can keep the “content management” part of the WordPress CMS that you know and love, and outsource your front end to virtually any other software you want, as long as that software can make requests to the WordPress API.
This is ideal for site administrators and content creators who are used to WordPress because their experience will be the same, Popov explained. "Content is still being generated in WordPress. So creating and publishing posts in WordPress is the same. They can still manage menus and other options in the same way, too," he said.
This set-up is also beneficial for front-end developers who want to work inside another application, use different coding languages than what WordPress uses, and/or add a front-end framework like React to make their jobs easier.
Additionally, what if you need to change your front-end system? Or, what if you want to redesign your site, or build it back up from scratch? Headless WordPress arguably makes these all easier, since your content is decoupled from the front-end. You can alter your website’s face as much as you want, but the content remains unchanged.
When starting with WordPress, you’ll be using it for your standard desktop and mobile websites, and that might be all you need it for. However, some scaling businesses may want to send their content to additional interfaces, like mobile apps, social media sites, smart devices, and virtual assistants like Alexa.
If this is the case, a headless CMS can serve as a centralized source for multiple publishing channels. In his WCEU session, Popov explained that one WordPress installation feeds many headless channels. "So site admins add content [in the back end] that can be used by any website, mobile app, or any app that reads data," he said.
Additionally, when you make a change to some content in the CMS, this change is automatically reflected across every device connected to it.
Imagine trying to do this with a traditional CMS. You’d need to reformat your content for every interface — that’s simply not scalable.
"A headless website is server-side generated so the website visitor has no relationship to the database," Popov explained in a follow-up interview to his WCEU session. This is great for security reasons. "A hacker needs something to hack and with headless, they have nothing to hack," he said.
While it won't be impossible to locate and access your database, it will be much more difficult if your front end is separated from your back end.
Again, there are things you can do to protect your WordPress site without going headless, but the security benefit is one more bonus of a headless setup.
Drawbacks of Headless WordPress
Before you start messing with your WordPress back end in an attempt to go headless, keep in mind that this solution isn’t ideal for the majority of WordPress users.
"You need to know where to adapt this technology — not to adapt just to adapt it," Popov said in a follow-up interview.
"If just starting a website or limited in budget, you can use the traditional approach. Headless would be a big investment that might not be a smart choice when starting, especially if you're not after a big campaign," he said.
On top of the necessary skills, running a headless WordPress website is a significant time investment — you now have two systems to look after instead of just one. If you’re not publishing content at a high rate, then the time, cost, and energy needed to run such a website aren’t worth the switch.
That’s why you tend to see headless configurations adopted more often by larger companies with enough resources to handle the job and enough content and channels to justify the investment.
How to Set up a Headless WordPress Website
If you’ve weighed the pros and cons of headless WordPress and decided it’s worth pursuing, there are several ways to go about it. Your method will vary based on your technical expertise and resources, preferred languages and frameworks, and your preferred WordPress host that can offer headless hosting.
We can break down the different approaches to headless WordPress into two general categories: plugins and coding it yourself. Let’s briefly discuss each method next.
Use a plugin.
WordPress plugins typically act as workarounds to writing code yourself. This unfortunately is not the case for headless WordPress plugins, which still require you to be well-versed in relevant programming languages and API concepts in order to build your front-end and make requests to the API. However, there are a couple notable (and free) plugins available that can make your life easier.
The main plugin we want to highlight is WPGraphQL, which lets developers turn their WordPress installation into a GraphQL API. What this means is that developers can create their own data schemas that any front-end client may use to retrieve data from your headless CMS. You may prefer a GraphQL-powered API over the WordPress REST API if you want to write your own data schemas and write runtime code that dictates how your API handles specific requests.
If you’re interested in headless ecommerce, CoCart is another WordPress plugin to consider. CoCart takes your WooCommerce store and puts a headless API on top of it, allowing front-end clients to request store resources like product and cart contents. This plugin can be highly useful if you want to launch a store on multiple platforms (e.g., a website and a mobile app) and manage your content from one WordPress/WooCommerce back end.
Lastly, once you’ve set up the front end of your headless site, you can use the Headless Mode plugin to send anyone trying to access your old WordPress site to your new front-end address. This plugin is very simple and ensures returning visitors won’t be confused trying to access your old site after you’ve changed URLs.
Code it yourself.
While plugins make implementing an API easier, you can’t beat the DIY coding approach if you want flexibility. There are many tutorials online that explain in-depth and step-by-step how to implement a headless configuration in your copy of WordPress.
For those brand new to headless WordPress, the best step-by-step guide to working with the WordPress REST API is this one from Smashing Magazine that walks through each step of the process with code snippets that you can use yourself.
Rather than building the front end of your website from scratch, we’d also recommend learning a front-end framework that handles much of the heavy lifting for you. Gatsby is one such framework that’s notable for its compatibility with WordPress. With it, you can manage your content through WordPress. Then, deploy your website through Gatsby’s cloud service while enjoying the performance boost that Gatsby gives you.
For more info on the improvements that Gatsby offers, check out this video from the developers:
Need a more flexible WordPress? Try going headless.
While headless WordPress will not end traditional WordPress as we know it, it’s a feasible option for businesses large enough to support the cost of implementation and maintenance. It might seem like more work at first to get started, but a headless approach could save you tons of time down the road and grant you more front-end flexibility than WordPress ever could out-of-the-box.
Editor's note: This post was originally published in November 2021 and has been updated for comprehensiveness.