5 Reasons you may (or may not) want to use Decoupled WordPress

You are probably here because you or your team are considering using decoupled (headless) WordPress. Welcome, if you arrived here and you are not familiar with WHAT headless WordPress is, check out our guide An Overview of Decoupled WordPress before continuing. Ok, I have spent a lot of time on calls with clients and time in forums seeing people succeed and struggle with their choice of decoupled WordPress. I will share why I think they found success, and why they struggled.

A Tale of Two Questions

We are actually asking two questions here. Should you go headless? Should you use WordPress? Maybe you have already answered one or both of these. Maybe you have not. It is important to know where you stand.

A great reason to use decoupled WordPress is that you already use WordPress and leveraging APIs is a natural added benefit. You save on retraining many of your teams on completely new software and are building on past investments. If this is you, then the question that really matters is, should I go headless?

For the sake of this article, this is the question we will focus on. I will assume you have wisely chosen WordPress and are debating whether to build your UI outside of the traditional theme and template engines.

⚠️Warning: technical chops required⚠️

Headless WordPress is great for some, but it is horrible for others. If you are not familiar with the Needs Stack, go read Jason Cohen’s article on the matter. Okay, welcome back, or not. Choosing headless WordPress moves you a level down the needs stack. In other words, you are choosing a lower level of abstraction. By choosing less abstraction you now have the power to build more custom and powerful features for yourself. But now you must build those features for yourself, instead of working within the time-saving confines of the higher abstraction level.

This may not be true forever. I know folks who have ideas around building new abstractions on top of headless WordPress so that you can have many of the benefits of headless without the extra work. But those are mostly ideas for the moment. Some of them are taking early forms in projects like Faust.js and the now mostly defunct Frontity. All this to say the decoupled world is much less mature in its tooling.

This means it has a higher technical bar for developers, more problem-solving should be expected, and custom solutions are needed. This means your team needs time and expertise to build headless WordPress or you will be paying your agency higher fees for the time and expertise required. If your business needs require this level of customization then it might very well be worth it. Just know what you are getting into.

This point also underlies all the following points.

Performance

If you can not optimize WordPress, you can not optimize headless WordPress. I had a WordPress agency approach me in the early days about moving their WordPress site to headless WordPress using Gatsby. Their driving reason was SEO. This was the early days of Google letting site speed and performance affect SEO. I should not have accepted this work. There was so much they could have done to optimize the performance of their traditional WordPress site. That was the work they SHOULD have done. They would have gotten a better result and not had the headache of managing a decoupled WordPress site.

I have chatted with a lot of folks since who have fallen for the performance buzz of static and headless, they think they need these things to be fast. They usually don’t. If performance is your issue, hire an expert to evaluate your current solution and listen to their advice. Invest in the existing architecture.

If you have done this and are still struggling to get what you need out of WordPress, or the investment required is similar to that of building something from scratch, then maybe you have a reason to look at other solutions. But that does not mean headless WordPress will solve your problems. There are many things WordPress is just not good at, particularly in the performance category, make sure choosing headless will actually solve your issues. Even if it will help, other solutions may be much better at solving your nitch performance issues.

Does it feel like I’m trying to talk you out of headless WordPress? I’m not but see the above warning. Headless WordPress can be amazingly powerful, but with great power comes great heartache. My job was, and the goal is, to make sure people understand what they are getting into and that this decision is actually providing benefit.

Content Distribution

Do you have a content team pushing out lots of content? Are you looking to send the content to various sites, apps, and devices? Then headless WP might be for you. The headless CMS was invented in the app age. When folks wanted to be able to publish content once and allow others to consume that content across a variety of apps, devices, and mediums. WordPress is really good at websites. Decoupled WordPress allows you to expand to mobile apps, and innumerable other devices and mediums.

But do you need a headless site? WordPress has the benefit of not being only decoupled/headless. If you are building an App, great, start using the API and leave your WordPress site on the classic WordPress theme and Template engines. There is no need to move your site for the sake of an app or other devices.

Multisite? Well, hold up. Why you could build a variety of sites using a single API, PHP is not without the ability to fetch content from an HTTP API. Maybe you can keep using classic WordPress across other sites and they only pull specific content via a decoupled HTTP API on another WordPress instance?

There are always simpler solutions that do not require you to bet the farm on FULL headless WordPress. Rely on technical folks to evaluate the possibilities and the tradeoffs in simplicity, time, and reliability before making hard decisions. It is really tempting and easy to start from scratch, but that does not mean starting from scratch is the best decision. Wherever you land, decoupled WordPress can give you the power to publish once to all your outlets without copying and pasting content and formatting across platforms.

Content Type

WordPress is really great at long-form content like this guide. It is really bad at being a database. With tools like Advanced Custom Fields and custom database queries it is possible to make WordPress do what you want, but should you?

I have seen so many folks building queries in GraphQL that will absolutely destroy a WordPress server. The same query in PHP would also do this. At the end of the day, you cannot get around the fact that WordPress was designed for a certain type of content. Complex filters and searches are not its strong point. We can hope all we want that WordPress improves this in the future, but I would not be betting anything on it. If you are building a SaaS or some other “app” like experience, WP is not a good idea. Content-heavy sites are great though.

A great example is a company blog. Let’s assume you are running a SaaS with a whole marketing site and app that runs on a separate stack from the blog you spun up in WordPress. You are looking to simplify. Going headless is super smart. Your content producers will still use WordPress but instead of managing a separate site and codebase for a WordPress theme, you can roll that into your marketing site. You have reduced code bases, upkeep, and unique technologies for your developers. If done well, your blog won’t be a forgotten stepchild of your dev team and will be kept updated with all marketing site changes to the design team’s delight.

To code or not to code

So you use WordPress, how? Do you regularly install plugins to add site features, improve SEO, etc? You lose all this in headless. Not to say many plugins do not work, but to leverage them there is code to be written and integrations to be done.

Do you use page builders? This probably is not a great use case for headless. Whether it is your entire site or just some landing pages for SEO, page builders rely heavily on being able to control how content is rendered on a page. Headless fundamentally replaces WordPress’ ability to render content onto a web page. If you are relying on these, that work will now need to be done in code.

These complexities can be overcome. But that is deep integration work your developers must do to make your front end(s) and WordPress work together. If your content can work within a well-defined structure then that contract is easier than completely freeform.

Your content creators must understand the limitations headless put on their ability to leverage the full power of WordPress. They must be ready and willing to work with developers to accomplish their goals. This can be good! Often plugins create solutions at the expense of performance, security, or stability. The structured contract required for decoupled WordPress means engineers are involved at every step to make sure those things are not overlooked.

Conclusion

Decoupled WordPress can be a powerful tool. But it must be right for your team and use case. If you need multiple of the benefits above and have avoided the other drawbacks then headless WordPress will probably be a great fit.