Decoupled and Headless WordPress are at the forefront of current WordPress discourse. People are keen to know if these technologies are a good fit for their projects. However, there is a lot of confusion in the community regarding exactly what these terms mean and their implications. The situation is further complicated by people conflating the terms- Decoupled WordPress and Headless WordPress are two different things. 

In this post, we will demystify Decoupled and Headless WordPress. We will clearly explain each concept, their differences, and when it makes sense to use one over the other. We will also touch upon the technical and financial implications and overhead incurred when going for such setups.

Why do we need Decoupled and Headless WordPress?

Earlier, websites were pure static markup- hand coded HTML webpages styled using CSS. Users would visit a page, see some information, click a link, the browser would refresh and present a new page with new information.

The introduction of Javascript allowed users to manipulate elements on a page and see live changes without having to refresh it. Think animations, dynamic form validation, image carousels and dropdown menus. This made websites feel more interactive.

WordPress (and CMSes as a whole) revolutionized things by allowing editors to enter content and have the software automatically generate these interactive pages.

But while traditional WordPress allows for interactivity using Javascript and frameworks like JQuery, it has its limitations. When users want fast, app-like experiences, the traditional model of clicking a button, waiting for the server to process and send back information doesn’t cut it. WordPress data is locked behind the server.

This is where Decoupled and Headless WordPress come in. They unlock the data for us to manipulate it on the client side.

What is Decoupled Architecture?

In order to understand Decoupled WordPress, let us first discuss the concept of decoupled CMS architecture. In a decoupled architecture, we have a separation of concerns between how we store the data and how we access it, made possible by API.

With this separation of concerns, frontend and backend work can happen independently of each other. The API reduces the potentials for conflict to a limited, validatable list. As long as the developers are honoring the API contract – frontend developers consuming the API data and backend developers not changing the API data shape – everything works as expected.

What is Decoupled WordPress?

Decoupled WordPress is when select WordPress data is accessed or manipulated via an API as opposed to running PHP code on the server. This allows us to progressively enhance the UX/UI of a traditional WordPress frontend, add custom features to it, and also to integrate WordPress data with external services.

By fetching and manipulating WordPress data on the client side, we can introduce data hydration/manipulation functionalities such as live filtering, lazy loading, submissions that show a success message without a full refresh, etc.

What is Headless WordPress?

Headless WordPress is when a WordPress setup is used solely as a backend CMS and the frontend is completely separated. There is a “total decoupling.”

By completely decoupling the backend from the frontend, we can use WordPress as an independent source of truth to serve content to any frontend application- even to multiple different frontends at once, across multiple different servers, regardless of the coding language.

Difference Between Decoupled and Headless WordPress

All Headless is Decoupled, but not all Decoupled is Headless.

While Decoupled WordPress lets us selectively break out of the PHP constraints of traditional WordPress by letting us access certain subsets of WordPress data through API, Headless WordPress creates a complete separation between the data and its display/consumption.

Benefits of Decoupled WordPress

Decoupled WordPress offers several benefits:

• It allows for limited implementation of app-like interactivity that doesn’t require page reloading. Think functionalities like search, filtering, lazy loading, comments, etc. 
• It allows for easy consumption of data from other WordPress sites. For example, for cross-site syndication. 
• It allows for easier ways of exposing data for integration and interaction with other applications via API. For example, Webhook payloads to CRM, Business Automation, etc.

Benefits of Headless WordPress

WordPress Headless CMS offers several benefits:

1. No need to fight plugins for control of the design, since the frontend and backend are separate.
2. The frontend team doesn’t need to know WordPress. Similarly, the backend team doesn’t need to know frontend. This makes hiring as well as shipping easier and faster since both teams are truly independent.
3. The frontend team gains the ability to use modern linting tools, preventing bugs from being shipped to production and ultimately making it easier to scale the site.
4. WordPress data can be used to power multiple platforms – a traditional website / Progressive Web App (PWA), a Single Page Application (SPA), mobile/embedded apps, or a static site hosted at the edge (individual instances of the frontend spun up as needed close to the users accessing it, instead of a single central server. Like a CDN but for the site itself).
5. Multiple sources of truth can be unified. For example, developers can create components or views fed by multiple WordPress Sites, a Logged In User flow with data fed by the ERP, etc.
6. Headless WordPress can unlock the doors for large networks to embrace multitenancy. Multitenancy is when a single codebase serves multiple isolated websites (tenants), and each website has its own data completely separate from others. Multitenancy has several enterprise benefits- stronger security due to isolation of websites, better individual scalability, as well as ease of creating highly customized experiences.

Disadvantages of Headless WordPress

The singular defining characteristic of Headless WordPress is that the WordPress frontend is completely removed from the picture. While this means freedom to do anything with the frontend, there are several implications: 

1. Most headless solutions today require rebuilding most of the frontend, if not all. A few existing frameworks can provide a headstart, for example, to replicate the WordPress template hierarchy. But overall the entire task is still more demanding than creating a fully-custom WordPress theme. This means a significant initial investment.
2. A lot of plugins (many for REST, most for WPGraphQL) don’t natively expose the API data needed to use them in Decoupled or Headless setups. This necessitates the usage of third-party plugins (paid and free) to expose data to the frontend (such as CoCart (REST) and WPGraphQL for WooCommerce (WPGraphQL), for WooCommerce). In cases where third-party plugin extensions are not available, custom PHP code is required. All of this adds to the initial investment. 
3. Making sure plugin updates don’t break compatibility or void the API contract requires continuous monitoring. This can be automated thanks to tooling, but a capable team needs to be in place to fix issues if/when they do break. This means recurring costs.
4. With the backend and frontend separate, development teams need to maintain two different stacks. This means hiring multiple specialized developers, which can be problematic for organizations with limited development budgets that allow for a handful of full-stack developers.

With these considerations in mind, let us look at the usage scenarios for Decoupled and Headless WordPress.

When to use Decoupled WordPress?

Decoupled WordPress is a sufficient solution in scenarios where:

1. Enhancements are primarily additive to the traditional WordPress experience or isolated to specific individual features.
2. The dev team is already familiar with modern WordPress Development (REST API, Gutenberg development)
3. Only some WordPress data needs to be consumed outside of WordPress.

When to use Headless WordPress?

Headless is the ideal approach in the following scenarios: 

1. The dev team has frontend developers who would benefit from working independently from the backend developers, and vice versa.
2. To provide utterly unique user experiences while maintaining strict brand guidelines and designs
3. To scale at the “edge” (for example, millions of concurrent users on an ecommerce site that cannot be page-cached).
4. To unlock the full power of the modern Web (assuming access to the talent required to implement it).

Traditional WordPress imposes limitations simply because it’s written in PHP and does not provide support for things that users take for granted in the modern web- like SPA, offline access, interactive user journeys, live feedback on interaction, etc. Headless allows website owners to keep using WordPress to manage the content, and use the ideal tool for the job on the frontend, be that static HTML, NextJS via React, iOS Native, etc.

This is as opposed to Decoupled WordPress, where the approach is to Frankenstein the ideal UX for a required feature on top of existing WordPress.

5. The traditional WordPress site is so fragile that updates are an “all-hands” nightmare.
   

On truly custom sites that have a lot of custom code and/or ecosystem plugins, an update to one thing is more likely to conflict and break something else. Combined with bad release hygiene in the ecosystem (plugins don’t use SemVer; they often bundle bug fixes with changes to the frontend or new non backwards-compatible features), an urgent update usually requires a team of developers checking every page of the site to make sure things didn’t break.

In Headless WordPress, the only changes that could break something on the frontend are those that change the API contract (which a build tool will warn about automatically), and not, for example, every new CSS rule in the stylesheet. This way there’s less to test, less to fix, and it takes fewer company resources and less time to keep the site up to date.

What’s in store for the future?

Decoupled and Headless WordPress unlock the ability to implement highly-interactive app-like experiences on our websites, while allowing us to use the CMS for its intuitive editing experience, effortless content management, multilingual support, easy SEO, and other invaluable features.

The barriers of entry to Headless WordPress are getting smaller every day. New WordPress features like the Interactivity API and Block Bindings API, plugins like the WPGraphQL ecosystem, starter frameworks like Faust.js, WordPress VIP’s Mesh API, and other open-source contributions keep pushing towards the common goal of making Headless WordPress plug-and-play. 

Are you considering Headless WordPress for your project? Contact Us.