Going Headless with Craft CMS

You can think of a traditional CMS based website as two major components.

• The first is the “head”, which is the component that the website visitor sees. This consists of the templates, the design of the site, and the aspects of the site a public user would interact with.
• The second is the content management side of the website, which only content authors and admins can access.

A headless CMS only has the content management features, and that content is made available in a format that other apps or websites can read, generally without restrictions on how that content can be presented or styled. It is up to the one (or many) separate “destinations” (the website, mobile apps, etc…) to present that content to end users in a way that makes sense given what the user wants to accomplish.

For Craft CMS specifically, to go headless basically means foregoing Craft’s template rendering capabilities entirely, and instead serving CMS content as structured data over a web API.

In the world of mobile apps, this is not a new concept. In most cases, a mobile app will need to “phone home” to push or pull data from a central data store. A headless CMS brings this same concept to the web, allowing a public website to be a separate app and codebase from any CMS that delivers content. The consumers of this data are typically (but not always) JavaScript-based web frontends or mobile apps. Tools like React, Angular, Vue, and more are popular means to consume data from a headless CMS and display it to users, typically with more advanced interactivity, like robust searching and filtering, dashboard-like interfaces, and user account management functions.

Advantages of headless Craft CMS

When redesigning or replatforming your content management system, deciding whether or not to follow the headless model can be a major decision. Going headless is a core shift in the underlying approach, and the pros and cons should be weighed against total development level of effort, the initial investment of time and money, and the total cost of ownership over the years.

Headless enforces separation of concerns and reduces risk.

It may sound obvious, but a CMS is meant to manage content, allowing content authors to write, edit, and manage potentially large volumes of written content, image assets, and files. How that content is presented to users doesn’t need to be a concern for a CMS. There are other tools available that specialize in displaying content in intuitive and attractive ways. As organizations move to microservices-based architectures and decoupled components, there are fewer reasons than ever to have a single codebase handle both content management and content presentation.

Because it doesn’t need to manage how content is presented to end users, a headless CMS has a much smaller scope of what it is concerned with. Making changes and feature updates to that CMS is thus less risky, as it touches fewer moving pieces. In the traditional model, adding a new field to a CMS can affect many templates and components on a website, and to make a change like this can require a lot of QA. For a headless CMS, developers only need to ensure that the structured data output reflects that CMS field change, ideally using automated testing tools. By using sound API versioning techniques, the developer can verify that these changes do not affect any of the websites or apps that are consuming the data from the CMS.

To content authors, the experience should be exactly the same. A headless CMS should not have any additional limitations on how content is managed, and the opposite is often true, and the CMS is often more flexible when deployed in a headless configuration. In a headless CMS, the author experience is still paramount and does not need to be hindered in any way if built correctly. As Brandon Kelly (CEO of Pixel & Tonic, the parent company of Craft CMS) announced at the Happy Cog NYC office in 2019, Craft has first-party support for a headless CMS configuration, including an enhanced live preview and other author experience niceties.

A headless CMS is typically less costly to own over time than a traditional CMS based website.

Developers can now more reliably roll out changes to your CMS, with less testing and QA effort, and fewer bugs or issues in production. This will allow your team to iterate more quickly, get new features and functionality to market faster, and churn through your product roadmap at speed. In the traditional single codebase website model, you have a greater chance of incurring technical debt that will cripple your ability to make changes quickly and reliably, even within a few months of the initial launch. By deploying a headless CMS, you can reduce that technical debt and total cost of ownership.

How to display content

If you’ve settled on deploying Craft CMS in a headless configuration, an equally important decision is how to get that content in front of end users. In the traditional Craft CMS configuration, this would mean building templates using Craft’s templating language, Twig, and having users access the same server and app the CMS authors use.

With a headless CMS, we have many more options:

• Deploy a separate, lightweight web frontend app using any number of popular stateful JavaScript frameworks, such as React, Vue, or Angular. These web frontend apps can be extremely light and fast, pulling data from an API powered by headless Craft CMS. They can either be single page apps, rendered entirely on the client side in the browser, or “universal” apps that are a mix of server and client side rendering.
• Launch native mobile apps for iOS and Android, each pulling and pushing data to your central Craft CMS content hub via those same APIs. This can extend to apps on other platforms as well, such as Apple TV, Alexa enabled devices, smart watches, and other smart-home or IoT devices.
• Deploy a static version of your website or app, following principles of the JAM stack, using a static site framework such as Gatsbyjs. These can be hosted on extremely lightweight and cost-effective hardware on any number of Platform as a Service providers such as Netlify or Heroku.
• Integrate with a bigger data pipeline, pushing and pulling data into a content warehouse on Amazon Redshift or Google BigQuery for advanced business intelligence reporting, or into an advanced search engine data store such as Elasticsearch or Algolia.

Building a site with a headless CMS requires some sort of way to access the data, generally via an HTTP API such as REST or GraphQL. The most recent versions of Craft CMS supports both options out of the box, either via the first-party Craft CMS plugin Element API or native GraphQL support, which can more flexible than a REST-based option. Prior to Craft 3.3, our own Development Director Mark Huot developed and maintained the popular open source CraftQL plugin for Craft CMS which provided GraphQL support before it was baked into the core CMS.

For more robust or complex projects, we at Happy Cog will typically build custom Craft CMS modules for either a REST or GraphQL API, complete with enterprise-ready features tailored to the project. This often includes API versioning, request rate limiting, secure authentication and authorization for clients, uptime monitoring, cloud-based autoscaling, and extensive endpoint documentation. Each build is slightly different, and for large scale Craft CMS sites, out of the box headless API solutions often are not sufficient to meet business goals.

Also announced at a recent Craft Dot All Conference, Craft’s parent company will be releasing a headless software-as-a-service version of its CMS called Craft Cloud, allowing sites to be powered by Craft’s headless backend without setting up or maintaining any servers. We expect Craft Cloud to be a great entry point for sites to use Craft as a headless CMS.

Headless is not right for every project

If we are separating the CMS from how the content is presented to end users, we will now have two codebases. There are many advantages to this, but one downside is that the initial investment in both time and money is likely larger at first that it would be to build a traditional Craft CMS website that handles both content entry and content presentation. When splitting those components into two codebases, there is some duplication of effort and the total level of effort increases. It’s not a major jump, but if your goal is to launch as quickly as possible with the least amount of effort, headless may not be the best route. However, there’s a trade-off for not starting headless. If you ever want to use the data in your CMS for anything other than the website it was built on, you’ll have to “retrofit” your instance of Craft CMS to become headless, which is much more costly to do after a site is built rather than during the initial build process.

We love headless Craft CMS builds at Happy Cog, but they aren’t always the best choice for every project. Sometimes, the traditional single app and server model can perfectly support the site’s goals. In those cases, there may not be sufficient benefit in using a headless configuration to justify the up-front investment. Similarly, if you are confident that the data in your CMS will likely not need to be consumed on other apps or websites, either now or in the future, headless may not make sense for you.

However, if you are looking for an extremely flexible headless CMS, going headless with Craft CMS can open the door for many possibilities. At Happy Cog, our developers are Craft CMS experts and we’re proud to be an official Craft Service Partner.

Contact us to discuss whether going headless is the right step toward meeting your goals.

Illustration by Ashlie Boyce

Back to Top