The front-end of Headless CMS

I wrote a blog on what Headless CMS is all about  on my agency site back in December. Partly to help explain to our clients what this technology is all about, partly to help crystalise some of my thoughts on the subject.

I’m currently embarking on an interesting project to build a set of tools to build a front-end website in PHP based on Headless CMS technology. My aim is to open source this front-end code, though we need to prove it first on a few projects.

I thought I’d blog about my experience and findings here. The following is a short technical focussed intro to all this.

Why is Headless good for developers?

Multiple content sources

Most websites these days are not made up of content from just one CMS, it’s quite common for a site to require content from multiple sources. That may be a CRM, an internal business system, social media feeds, other sites, the weather in your garden, the list goes on.

The central idea of Headless CMS is you use the CMS just for managing structured content. You then build the front-end site in whatever tools you wish, theoretically freeing up your dev team to work as they wish, faster and more efficiently. Content is pulled into website over an API.

If your site is built up of content from many different sources, the Headless CMS paradigm works pretty well. The main page content is pulled in from a Headless CMS API, so it’s just as  easy to pull in content from different locations. Some people call this a decoupled front-end site.

Flexible front-end

It’s easy to be constrained by the chosen CMS on a project, to have to write HTML or CSS in specific ways to fit in with how the CMS does things. There are few CMSs that really allow your front-end  to be completely independent.

The Headless CMS approach frees you up to build front-end templates exactly as you’d like. More importantly, it’s easier to share front-end code between projects that may use different CMSs or content sources, but the same decoupled front-end approach.

CMS independence

With Headless you are no longer so dependent on the CMS. In the good old days if you changed CMS, you usually needed to rebuild the site from scratch. This isn’t very efficient and it always seemed to me there should be a better way.

If your front-end is separated from your CMS you have the flexibility to change the CMS platform and keep pretty much all your front-end site code. You just need to update where the content is read in from. This is a good example of separation of concerns, a well-established and beneficial programming principle.

Performance and security

Websites built in large CMSs can be slow and cumbersome. This is usually due to the large amount of code they run, or the complexity that is understandably present to ensure a CMS meets the varied needs of its many users.

A front-end site build with Headless is smaller, has less code and therefore less attack vectors. You can build only what you need and ensure you build that well.

People often complain about CMS security. In truth large projects like WordPress and Drupal have fantastic security teams who respond quickly to any issues. However, the main issue I’ve found is with third-party plugins or modules, which rarely have the same focus on security and code quality. Avoiding a dependency on these can be a good thing for both performance and security, though comes at a cost since you need to build your own functionality.

Developer experience

One key criteria for me is to make front-end development easier for my team. CMSs like Drupal have become massively complex and its difficult to find good front-end developers who are expert at core skills like HTML, CSS and accessibility who also know the ins and outs of a complex CMS such as Drupal.

Ideally I don’t want a CMS to hold my team back. I want them to be able to build a front-end we can just implement on a website quickly and easily.

Why PHP?

I’m very experienced in PHP, since I’ve been coding in in for two decades. I’ve worked on loads of PHP projects, mentored team members in the language, attended a ton of PHP conferences, and seen both the good and bad side of the language.

PHP remains one of the most popular languages on the web. It’s pragmatic, runs almost everywhere, it’s easy to use and with the great strides made in both the PHP language and community in the past decade it’s a great language to work with.

Hey, what about JavaScript?

The world of Headless CMS seems to be dominated by JavaScript Single Page Apps (SPA). There’s even an acronym for it, the JAM Stack (JavaScript, APIs, Markup). You could be forgiven for thinking you have to write a Headless CMS front-end in JavaScript!

In my experience you need to have a very experienced set of JavaScript developers to write successful and maintainable SPAs. The world of JavaScript tools changes quickly, it can be difficult to keep up with the change of pace. JavaScript templating tools also increase complexity, often mixing HTML and CSS directly in JavaScript, breaking that old separation of concerns principle that has served me so well.

I don’t want my front-end team to have to be JavaScript experts in order to build a website.

Serve content as HTML

Jeremy Keith’s excellent (and free) online book Resilient Web Design states his simple approach to web design:

  1. Identify core functionality.
  2. Make that functionality available using the simplest possible technology.
  3. Enhance!

If you’re serving content to users the simplest available technology is HTML, not a Single Page App. Serving static content with JavaScript simply doesn’t feel like a good idea to me.

While there are solutions to get around this in the JS world (e.g. NuxtJS), they aren’t often used well and the complexity JS frameworks bring isn’t always a good thing.

In my opinion using PHP to serve HTML to users is a more resilient solution. JavaScript can then be used to enhance websites.

The Front-end

I’m focussing on the front-end since it’s what we build for our clients. There are enough Headless CMSs out there, and all you really need is a half-decent API to grab content and display it on your site.


Whether you use PHP, JavaScript or Python to build a front-end site with content stored in a Headless CMS, there are challenges. Here are a few..

Complex content fields

We use tools like Advanced Content Fields in WordPress to create more flexible and structured content for pages. However, this creates a complex, nested content object in the content API. Something that will require some cleaning up to make it easy to use in templates.


Out-of-the-box search in a CMS is often pretty shoddy. These days with tools such as ElasticSearch the expectation is for fast, relevant search results.

After reading Simon Willison’s excellent 24Ways article on building fast autocomplete search in SQLite and Python I thought why not use SQLite. It has good support in PHP and also means there is no dependency on a database. For larger projects I’d look to use ElasticSearch, but that can come in the future.

Listing and pagination

Not all content APIs are built the same. WordPress, for example, decided to omit pagination when listing things like blog posts for a website. Not entirely helpful! [edit] Actually, WordPress’s REST API is pretty clever and hides the total results data in a header called “X-WP-TotalPages.”

I have seen a JS-built Headless CMS website which loaded the entire set of news articles over the API in order to build pagination, which is really not the best approach.

SQLite again to the rescue! My approach is to use SQLite to sync data from content APIs to help build listing and filtering pages.

Content preview

Another missing feature for sites built with Headless CMS is content preview, a very useful feature for clients to review what a page will look like before it’s published.

The obvious solution here is to build a small WordPress plugin to display a preview page via the front-end site, using some form of authentication to help ensure the preview function is kept private.


These are a few of the topics I’m looking at in this project, I’d be interested in anyone else’s experience of this or comments on build performant front-end sites with Headless CMS!