The Disappointing Quest for a Headless CMS

DZone 's Guide to

The Disappointing Quest for a Headless CMS

Love web development and blogging? Since you're on DZone, it's safe to say yes. Read on to see the pros and cons of some prevalent headless CMS platforms.

· Web Dev Zone ·
Free Resource

In 2017, my blog has been powered by Hexo.js. However, I am looking for a replacement since Hexo.JS is lacking crucial features.


TLDR : HexoJS is too limited, I want online post edition!

I have recently been working to replace the technology powering my blog. A major point is that I am disappointed with its theme. I would like to replace it, with a new technology Vue.JS, which I have already discussed here.

Since I am replacing the whole front-end, I have been using the great plugin hexo-generator-json. However, I still have major issues with my assets (stored with the posts) and it is not really compatible with a CDN solution.

The second feature I am missing is the possibility to edit my post online. I am a user of Medium and I love the mobile application that allows me to create and edits my posts as well check out my blog's statistics. A thing I did not think of at first is the impossibility to create new posts with Hexo.js without a computer. Indeed, to generate your site, you have to generate it, using a full Node.js environment, commiting, pushing  your modifications on GitHub, deploy the docker container, and so on. A lot of tasks I have mostly automated but yet, I don’t have a CI Environment available for it.

I did not want to switch back to Drupal or Wordpress, which I found to be a bloated solution, i.e. slow and hard to tune.

I wanted a compromise : why not having a NoSQL Database, a light REST backend, an AdminUI and that’s all?

At the beginning of this post, it was my plan to build this backend, but I decided shortly to concentrate on the content, rather than on the code.

Fortunately, the technologies have evolved and I made a list of Headless CMSs/API-First CMDs and tested them.

Headless CMS, What Is It?

I won’t spend too much time on the details, a good description has been given here.

Basically, legacy/traditional CMSs are highly coupled solutions where the following components are tied :

  • Database: SQL Databases
  • Backend: PHP or worse
  • Front-End: Templated front end or theme highly coupled with the backend API. Unmodifiable at best, throwable at the worst.
  • Separated WS/RPC: External service to access the backend data, not used by the front-end.
  • Admin UI: Bundled Admin UI.

Usually this kind of CMS is stored in one big block called Wordpress, Drupal, Joomla, and so on.

The good news is that even these famous solutions are evolving to apply the following modern and well-known principles:

  1. Decoupled front-end: CMS frontends should be decoupled. The UI will have access to the blog data and content using a REST API. UI for Headless CMSs are usually using technologies such as Angular, React, or Vue.js.
  2. Responsive front-end: Headless CMS enales the possibility to create various UIs depending on your devices, smart watch, website, search engine, etc.
  3. NoSQL Database: Handling documents and content is the speciality of NoSQL databases, allowing you to add your own custom fields, categories, and organization.
  4. Framework: Such Headless CMSs should provide libraries or frameworks to access the content and handle the security as npm modules and so on.
  5. DevOps: Such a solution should be dockerized.

Here's what I am expecting a Headless CMS to contain:

  • A REST backend.
  • Documented RESTFul APIs.
  • A database driver compatible with NoSQL.
  • A bundled Admin UI accessed by an API to the REST Backend.
  • A Docker image or Docker Compose.
  • The possibility to add custom fields.
  • The possibility to handle markdown format for the edition.
  • Cloud FS Storage for my medias.
  • Optimized solution: I don’t want a new WordPress installation.
  • Node.js solution: I want a lightweight solution.
  • Self hosted solution: I want to deploy it on Google Cloud.


The list of my experiments and my opinion about them.

Docker-Compose was not running (I used this project).
The Docker instructions worked for me.

I launched it and soon enough I received a lot of technical alerts killing the pleasure I get from a fresh installation.

Directus / Error message

My last blocking point, and the reason I rejected this solution: I did not find any way to create a content category (called table) in the admin UI. Seems to manipulate the SQL database to create them: no thanks (rant here).

GetMesh: Meh

Uh-uh. A Java solution to power a small blog: no thanks.


Drupal and Wordpress: Hydra CMS

Too big, too well-known. The REST API is for sure the next security hole of these solutions.

But the reason for my rejecting these solutions is that the UI cannot be separated from the backend!

And why would I like a UI embedded in my backend when I want to create an SPA website?

I will use them when they have deleted their UI from the installer.

I call them HydraCMS.

GraphCMS: Hipster$$CMS


Looks great, but I want my own self-hosted solution and don’t want to pay for that.

Site here.

Ghost: GirlyCMS

Honestly, I had a crush on Ghost. Sexy, a great installer, a great documentation, everything to tempt me like an attractive woman.

The problem is that Ghost has almost everything to charm me but it has an embedded UI!

I don’t want a UI, I want to build mine.

Apart from that point, GhostCMS is really great.

Ghost CMS

It even has a Slack integration and loves Markdown!!

Ghost CMS Site

Cockpit: Blind CMS

Cockpit CMS

Listed in the Awesome CMS ListCockpit CMS is a rather small solution.

The good points are :

  • Docker is working fine. 

  • The concepts and architecture are OK.

  • Nice AdminUI, I really appreciated the ways there are to create my collections**

But what really disappointed me was :

  • No documentation (REST and so on). 

  • For a developer, it’s unusable PHP: There is no documentation and the REST API is coded in PHP... meh.

In summary, I think that this project goes in the right direction but took a tough and spiky path. PHP is clearly not the appropriate language for such a solution. Compared to an Express server, the amount of work to be delivered is too high.

It really needs more (active) contributors to create a good solution and fill the big documentation blackhole. I cannot help since I don’t want to code in PHP again, but the solution could be great.

Site is here.


Well, at first glance, I rejected it, as I could not find any Docker images. Or the few I found were not working.

But my first attempt was dumb. KeystoneJS is not a Headless CMS by itself, it’s rather an implementation of a CMS, fully customizable to create your own blog!

And it's powered by Express and Node.js, two technologies I am particularly fond of!

The site is here.

The positive sides of KeyNodeJS:

  • A slick project creator using Yeoman!
  • Modern technologies, I think the best to create a CMS.
  • The bundle contains what I am expecting (AdminUI, REST Backend, NoSQL Database(MongoDB)).
  • Fully customizable collections and so on.

The negative points are :

  • Maybe too much code to begin with.
  • What is the maturity of the base implementation ?
  • How much effort is required to build your own website?
  • I have not found an npm module to build a REST Client.


I have rejected most of these solutions.

  • I tried two times to install and migrate my data in DirectUS but I gave up. I don’t believe in the concepts.
  • The lack of API Documentation in Cockpit (HTML or a la Swagger) is blocking my attempt to use it and migrate my data. The fact that the solution is developed in PHP is blocking my wish to support them. And I don’t like much PHP REST backends to be honest.
  • I really love Ghost but I don’t want their UI, I want mine. Otherwise, I would have used it.
  • I tried to use Drupal and Wordpress, but the requested system resources + the fact I cannot disable the UI are a big NO for me.

The consequence is that I am using KeystoneJS and I hope I won’t have too much work to power a new version of my blog.

Stay tune!

References :

cms ,headless cms ,node.js ,web dev

Published at DZone with permission of Sylvain Leroy . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}