The Complete Guide to Headless WordPress CMS

Last updated on

Summary (TL;DR): In this article, we are going to discuss what Headless WordPress CMS is, and offer you a complete guide on how to use and implement it.

WordPress is a magnificent platform. It offers accessible features for website design, and can be expanded to do almost anything through a plethora of plugins designed by experts. However, sometimes your needs go beyond the scope of what the readily available WordPress themes and plugins can offer. Writing frontend for WordPress means writing your own plugins and widgets, in PHP no less. I’m sure I don’t have to tell you what a pain that can be.

Fortunately, there are solutions. One of those solutions is Headless WordPress CMS. This post will guide you through what it is, why you would choose it, and when you shouldn’t. In addition, we’ll review the popular stacks and frontend solutions usually integrated with WordPress as a headless CMS.

Before we do, let’s briefly define what CMS is, and what makes a CMS headless.

What is a CMS?

CMS stands for Content Management System and is the back end of most websites today. Back in the early days of the internet, websites were built from static HTML pages. If you wanted to add another article or post to your website, you created another HTML file, linked to it from the menu, and added your content directly into the HTML.

Anybody that has any experience developing websites in the 90s will realize how inefficient this gets if you need to create new content on a regular basis. Thus the Content Management System was born.

The idea behind a CMS is that instead of creating an HTML file, everything about the content is stored in a database. A template is used as the front end, allowing the content to be inserted dynamically into the page.

One of the most popular CMS to date is WordPress. It makes sense as it is free to install and use, and has been around since 2003. Today, WordPress is used by 64.1% of all the websites whose content management system we know. This is 39.8% of all websites in the world.

WordPress allows for very seamless editing of content using a built-in editor. It also allows for quick and easy templating, using themes to change the way a page looks, and other editing tools to modify the structure of the website.

The open-source nature of WordPress also means there are numerous plugins that can further modify the way any WordPress website looks and behaves, as well as add features or integrate with other platforms.

What is a Headless CMS?

CMS solutions come in packages, and those packages contain many more features than a mere template and database. When you choose to adopt a CMS such as WordPress, the CMS itself dictates how your website will run. WordPress is coded in PHP, so any changes you would like to make to your website would need to be done in PHP too.

Sometimes when developing a website, you might seek to have more freedom. A headless CMS provides just that, freedom. Headless CMS is essentially just the backend without the frontend. That would include things like content creation, database management, editing, and user management. It would not include things like templates, themes, or any other aspect that is directly viewable to the end-user – the frontend.

(Source: WordPress & Vue.js: Headless Stack w/ WP REST API )

There are numerous Headless CMS out there, some of the most popular are Ghost, Strapi, and Netlify CMS. None of these can compete with the popularity of WordPress as a headless CMS solution.

Why should you use Headless WordPress CMS?

There are many reasons to use a Headless WordPress CMS, but most of them apply to any Headless CMS. So before I run down the advantages of Headless CMS, I’ll touch on why WordPress specifically.

WordPress is widespread

WordPress is by far the most popular and widespread CMS. Most people know what WordPress is, and many hosting platforms offer one-click WordPress Installation. If you wish to run a Headless CMS, but don’t want to fiddle with installations of other alternatives, WordPress is a clear choice.

Another good reason to use WordPress is that you can start out with WordPress as it is, with the coupled frontend, and later choose to chop it’s head off. Or vice versa, maybe you start out with Headless WordPress CMS, but later decide you would rather use the WordPress frontend? It would not be too difficult.

Multi-Channel publishing

Once the backend is decoupled from the front end, the backend can be connected to any frontend. Not only that, it can be connected to multiple frontends. You could have a website, a mobile app, and even have it served to Facebook or other social media platforms. Using a Headless CMS allows omnichannel marketing at its core.

(Source: What Is a Multichannel CMS? )

A tailored design

WordPress templates and themes are excellent and offer a much wider user base the ability to make beautifully designed websites. But some developers are very capable of designing their own websites to suit their own specific needs. A tailored design will always fit better than any off-the-shelf designs you may find.

It is also much easier to integrate a CMS into an existing website if you already have one and want to add content to it. Otherwise, you’d have to redesign your website in WordPress, which could become a real hassle.

Increased performance

The WordPress frontend is not fast. It is feature-rich and that can cause bloat. Especially if you’re not using some or most of those features. Slow-loading websites are a big problem, especially on mobile. Users may not wait around for your content to load and opt to move on. Making your website load fast is imperative so you may want to take performance into account in picking the head for your headless CMS. 

(Source: How Websites Slow loading can Eat Your Revenue – Dexecure )

Moreover, it is well known that Google considers website loading speed when ranking websites for appearance in search results. So if SEO is a priority? You may consider a different frontend solution than the WordPress frontend. A Headless CMS allows you the freedom to tweak performance to a much higher degree than the common tips to make WordPress load faster.

When you shouldn’t use Headless WordPress CMS

Headless CMS is certainly a very powerful tool, but there are certain disadvantages. Let’s have a look at the most prominent ones.


At its core, Headless CMS is not a plug and play solution. Headless WordPress CMS is in fact the exact opposite. You start by installing WordPress and then decouple parts of it. Not only that, a ready-made compatible frontend will be needed. Or you’ll need to build your own. Certainly not a task for everyone. I would not recommend a Headless CMS to inexperienced web developers unless tackling this is your way of learning.


With freedom comes responsibility. When you’ve developed your own front end, you need to maintain it, and maintaining code is time-consuming. WordPress’ frontend is definitely easier to maintain. It doesn’t often break, and when it does, there will be a wide community to help you figure out how to fix it.

No built-in editor

The WordPress post editor is a part of the front end. If you completely decouple the backend, you sever the connection to the editor as well. This means you will have to build your own tool or incorporate an existing tool such as Gutenberg (which happens to be the editor WordPress uses).

Beheading WordPress: How to set up headless WordPress CMS

The first step you’ll need to take, once you have WordPress on your server, is to remove the front end. Luckily, there is a plugin that can do it for you. The aptly named Headless CMS plugin for WordPress. The installation process is as straightforward as it can get, and should be as painless as installing any other plugin.

The next step would be to start working on your frontend. There are a few different approaches you could take here. You could choose an existing frontend, and attach it to your Headless CMS. You could create a Progressive Web App, or you could even develop your own website from scratch (though I would not recommend that in this day and age).


Jamstack is a popular web development platform, and it would serve well as a frontend for any CMS, Headless WordPress included. One of the strengths of Jamstack is loose coupling. Which, if you went through the trouble of decoupling WordPress, is probably something you want. I recommend this tutorial to get you started. It is quite in-depth.


If you are looking to fast track your development, but still maintain a lot of the freedom associated with Headless CMS, look no further than Gatsby.

Gatsby has a lot of similar features to WordPress, but will remain decoupled from your CMS, and as such will be easily replaced, or simply be a part of a multi-channel content stream. Gatsby’s own documentation is great for setting it up with Headless WordPress CMS.


Progressive Web Applications are similar to websites in many ways. Unlike other websites, PWAs employ a wide range of Javascript libraries in order to give users a native-like experience on mobile.

If you’re looking to develop for mobile, PWAs are an excellent way to do so without delving into native app development. You’d likely want to use a web framework like Vue or React in order to develop your progressive web app.

WordPress is great, but sometimes you want your own frontend and a headless CMS for whatever reasons it may be. In this post, we’ve gone over the reasons, methods, and approaches to setting up a Headless WordPress CMS.

There are clear benefits to a Headless CMS if WordPress’s frontend doesn’t meet your needs. But there are also disadvantages to writing your own frontend. We went over some midway solutions that allow more freedom while maintaining the benefits of a well functioning frontend platform.