Why use WordPress as headless CMS

This covers the theoretical half of my workshop at WordCamp Vienna 2024, on why to build a headless WordPress (WP) website. You can find the slides and code repository to get started with a fresh headless site here.

A headless website seperates the frontend (the part that displays pages and posts) from it's "Head", the Content Management System (CMS), which in this case is WordPress. This allows you to independently scale and optimize the frontend and break free from the traditional way to build WordPress websites.

Effectively, this means that WordPress is only used to store and maintain content, or data, and a more modern frontend framework like Next.js, Remix or Astro along with React is used to build out highly dynamic and interactive frontends.

But there's advantages and drawbacks to any technical solution, so let's get started and look into both, the main benefits as well as potential blockers from going headless:

The benefits of a headless WordPress website

Highly interactive and dynamic experiences

Using a headless approach with a modern frontend framework allows for the creation of highly interactive and dynamic user experiences. Traditional WordPress themes and plugins often struggle to provide the same level of interactivity without significant customization or performance hits.

You can of course still add the new Interactivity API, or a JavaScript library like Alpine.js, Vue or even React to power complex interactive components, but they will either feel glued on top of a very different ecosystem, or not allow for the same flexibility as when your entire frontend is powered by the same dynamic rendering method.

With dedicated frontend frameworks like Next.js, Gatsby, Remix or Astro, you can build features like real-time updates, advanced animations, interactive components or pages with complex state changes that are more difficult to achieve smoothly within just WordPress.

When Performance is absolutely critical

By decoupling the frontend from the backend, you can optimize each part independently. This means your frontend will act as a server side caching layer in between your visitors and your WordPress site. Instead of loading the entire WordPress PHP code to generate each page, these modern frameworks all have sophisticated caching mechanisms built in, to only fetch new data from your CMS when needed.

This directly results in a faster, more responsive site and not only improves the user experience but also has a positive impact on SEO, leading to better search engine rankings.

While it's not impossible to achieve great performance with WordPress out of the box, it usually means spending time on selecting the right puzzle pieces before building out a new website as well as spending more time on optimizing a sites performance after it's built, through caching and performance optimization plugins.

With headless websites, performance usually does come out of the box, with a great repertoire of features to further finetune it, and scoring badly on the performance front will take active effort or a misconfiguration of the underlaying technology stack.

Easily scalable development process

When working on a traditional WordPress website, each developer in a team usually has a local copy with it's own database, content and files running. Once a feature is completed, both the code, as well as the content have to be merged or manually re-entered.

A headless architecture allows development teams to work on the frontend and backend simultaneously without interfering with each other. Each developer works on their own copy of the frontend, but connects to the same backend, so all other content is shared and immediately accessible by the entire team.

This parallel development process can significantly speed up project timelines and makes it easier to scale your development efforts.

Quality assurance through modern dev tools

Modern frontend frameworks come with robust development tools that not only enhance the developer experience, but also allow for more effective quality assurance already within the development process.

Modern formatting, linting and code sniffing tools, that predominantly support the JavaScript ecosystem can be applied to all frontend code, including React components and templates. These tools are often more advanced than what's available in traditional WordPress development environments.

Common issues like user facing runtime errors, but also patterns that lead to bad usability and accessibility can be detected and potentially even auto-corrected by modern tooling, directly during the development process, but also as quality assurance steps before every deploy of new code.

Security / Microservice architecture / Multi-channel / web-scale

These are more buzzwords, used to describe the advantages of a headless website architecture, but while all of them definitively can be the reason why you should go with a headless approach, I found them to be more justifications after the fact, when the true reason to go headless was one of the aforementioned.

Yes, headless will be more secure by default (no login or database access from the frontend by default), can be used to more effectively strap together multiple services and backends, distribute content to multiple channels (different sites, stores, apps, TVs, whatever) and do the web-scale (whatever that means), but if these are your primary concerns, then you wouldn't be asking youselve this question, and already have a headless architecture setup.

Reasons not to go with headless WP

No support for Themes or Plugins

One of the biggest drawbacks of a headless WordPress setup is losing out on the extensive ecosystem of WordPress themes and plugins. These tools provide out-of-the-box functionality and design options that can significantly speed up the time it takes to get your website up and running. With a headless setup, you'll need to recreate much of this functionality from scratch, which can be time-consuming and require more advanced development skills.

Any plugins you install will still be available in the WordPress backend — so plugins like ACF, Admin Columns, WP All Import/Export or even WooCommerce are still great choices for your backend) — you will, however, have to reimplement your entire frontend from scratch, by pulling the required data from WordPress through one of the API options.

Setup time and initial development velocity

The initial setup for a headless WordPress site can be complex and time-consuming. Instead of using WordPress features like page templates, query arguments and the default routing structure, it requires configuring the CMS to serve content via APIs, setting up the frontend framework, and ensuring both parts communicate seamlessly.

This initial overhead, to basically re-implement a big part of the WordPress frontend core will slow down development, especially during the first week or two of the development phase and even more so, if your team is new to the headless approach.

New feature adoption speed might be slower

Even if you do decide that at the point of defining the architecture for your next WordPress project, be aware that future feature requests might not be as simple as just installing that one plugin. The great plugin ecosystem is both, one of the biggest advantages of going with WordPress, but also the reason carelessly maintained websites end up with dozens of one-off plugins, each dragging down the performance of the site further and further.

At the very least, building out new features on a headless website include first implementing the feature in the CMS (either through an existing plugin, or custom development), and then building out the user-facing frontend fully custom. This will take more development effort, but at the same time inevitably ensure a more cohesive, dynamic and qualitative web experience.

Conclusion

While you often could build out the same site, both with a standard or the custom headless approach to WordPress, certain types of websites (very interactive, dynamic or high-performing ones) just lend themselves to the headless approach, making up the lack in effectivity in the initial development duration with the much higher effectiveness towards building bespoke dynamic web sites, stores or applications.