An Introduction to Headless CMS

A headless CMS is a content management system (CMS) that’s separated from the front-end. In other words, it’s a CMS that provides only content through the API either using the RESTful or GraphQL. The term “headless” comes from the concept of removing the “head” (front-end) from the “body” (backend or the CMS) that provides the content.

If you’re familiar with WordPress, or other traditional monolithic CMS such as Drupal or Joomla, then this guide will be easy for you as we’ll be creating the front-end through their templating system usually using their built-in functions and the same language that the CMS is built upon. Let’s get started.

Why building Headless CMS?

Before getting into the guide, I would like to highlight the many advantages of building your site with the Headless CMS setup.

Firstly, with Headless CMS, you can hide the backend used on the site. As the backend is unknown or hardly discoverable, this may keep your site from being a target of attack like brute-force attack which is common if you’re using open-source CMS like WordPress.

Secondly, Headless CMS may help in your site’s fast loading speed as it will only make a request to the API and render the content on the fly instead of reloading the whole page when the user is navigating to a new page.

Thirdly, the developers may be able to break free from the CMS limitation on rendering the content. If the API allows editing the content, for example, the developer may be able to build a tool on the front-end for quick editing.

And last, but not the least, with Headless CMS, we can easily deliver content to various mediums other than the web such as; mobile and desktop app, IoT and IFTTT, etc. The developers can also use any language to render the content. So it can improve the overall experience for both the developers and the users.

Diagram of Headless CMS

(All icons by Icons8)

Headless CMS downsides

As good as it sounds, Headless CMS setup also comes with its downsides which you need to consider as well before jumping the ship.

First of all, there might be a high barrier to entry due to the technological knowledge requires to run Headless CMS setup. You will need two different domains to host the backend and the front-end, both domains will also need SSL certificate installed, and integrating 3rd-party service into the mix, and so forth.

Second of all, if you’re using a traditional CMS like WordPress, many plugins might not work out of the box. You will need to work it out yourself so the plugin data is accessible through the API.

Thankfully, with the vast community in WordPress, plugins are available to address this downside, for example, ACF to REST API to add custom field data added with ACF to the API, and WP REST Yoast Meta which will add the metadata generated by Yoast SOE plugin to the REST API as well.

How to build Headless CMS?

There are plenty of choices today to build a Headless CMS setup. Contenful, dotCMS, and ButterCMS are among prominent names in content API.

These services only provide the API, and the interface to manage the content. It is up to you how you’d like to present the content. These type of services usually provide an SDK for various programming languages to make it easy for developers to connect and consume the API.

Furthermore, according to, there are now around 50 of both open-sourced and closed-source CMS to get you up with Headless CMS setup. The list does not include traditional CMS like WordPress, Drupal and Magento which now have content API built-in.

Using WordPress as a Headless CMS

WordPress has REST API built-in since the version 4.4. The API includes endpoints to retrieve the post list and each post’s content, and edit the post. Once you have this API, you can start creating a Headless setup.

In this guide, instead of starting from scratch, we will be using Headless WP Starter which already has everything set up for us. It includes WordPress installation as well as the front-end setup that renders the content using React.js.

  1. Headless WP Starter requires Docker. So assuming you haven’t had it installed in your computer, you can head over to these instructions to install Docker and Docker Compose on Windows and macOS.
  • Next, we create a directory to host our sites.
  • mkdir wp-headless && cd $_
  • Then, we clone Headless WP Starter from the repository into the directory we’ve just created.
  • git clone .
  • Lastly, we run the following command to get the site up and running.
  • docker-compose up -d

    This process will download several Docker images from the Docker registry and spin up the containers, which may take quite some time to complete.

    When it’s done, we will be able to access the site from the localhost:3000, as we shown below.

    Loading WP Headless in browser

    Final thoughts

    I think that Headless CMS is preferable when the CMS theme or template is not enough to create the front-end experience you’d like to have, or when the content will be distributed in various channels aside from the Web. For a simple site, I believe that using a monilithic CMS is still the easiest way to go.

    Anyway, I hope you find this article helpful to get into Headless CMS.