An Overview of Decoupled WordPress

Alex Moon -  Last Updated

Defining decoupled WordPress

Decoupled WordPress, also commonly known as “Headless WordPress”, is a term used to describe using WordPress primarily as a back-end data API. As opposed to using the WordPress templating and theming engines for the presentation layer. Still confused? No worries, let’s break that down by reviewing WordPress and its feature set.

As you know WordPress and its plugin system can do a lot for you and your website. All these features fall into two overarching functions. First, WordPress allows content creators to write content and associated data. No matter the content, the WP ecosystem can store the data provided by writers, editors, SEO specialists, and more. Software that provides these features is known as a Content Management System (CMS). Second, WordPress renders stored content via its templating and theming engines into web pages for website visitors to consume. Keep these two functions in mind as we continue.

Building websites has changed a lot in the 20 years since WordPress was invented, we have different ways of rendering and templating websites. We also have mobile apps, car entertainment systems, TVs, game consoles, billboards, smart devices, etc. All of this means that we have new places to render the content in WordPress. Places that WordPress’ theming and templating system couldn’t dream of when it was built.

Decoupled WordPress is when you use WordPress as a CMS; then, through an API, use a separate software stack to render a user experience. That may be a website, mobile app, billboard, etc. Whatever it is, the data is still coming from WP. WP is functioning as a CMS, you may even be using its templating system for your website, but you are also driving other user experiences with its data. Using a single source of data to deliver data into distinct systems for various reasons is called multi-channel content delivery.

Decoupled WordPress Diagram

Decoupled even includes using a JSON API to drive JavaScript being delivered by a WP theme. Maybe you need real-time data, or something more interactive for your design. You’re no longer tied to the PHP APIs but are using a JSON API directly from JavaScript. The important distinction here is this is limited to client-side JavaScript, not a server application.

Decoupled WP in the wild

It’s fairly easy to identify decoupled WordPress, but very hard to define decoupled WordPress. This is because of the nearly infinite ways any engineer might decide to use a JSON API. Very commonly, they use it to build a website. Others choose to consume the data in a mobile app. Another might use it to create an article-sharing network among independent news outlets. Maybe some drive digital signage with their WP instance. The real thinker might even use a single WP instance to drive all the experiences at the same time.

However it is applied, decoupled WordPress is a powerful tool for publishing on a variety of platforms. But it’s not for everyone, and our next guide in this series will focus on helping you understand and communicate with your team why decoupled WordPress may or may not be a fit for the project you are working on.

Decoupled Technology

So what does the actual tech look like for this? There are two main technologies used for building with decoupled WP. WPGraphQL or the WordPress REST API. These are both great options for building decoupled WP. For more info on this topic checkout our guide comparing REST vs GraphQL API.

Alex Moon

About Alex Moon

Avid Open Source maintainer, a longtime developer, and vagabond.