As developers, we are often asked to weigh in on architectural decisions or provide recommendations on the technical direction of new projects. For developers new to decoupled architectures using headless CMSs it can be difficult to fully articulate the pros and cons to your teammates, managers, or potential clients. This article attempts to answer some of those questions so you know when you should or should not reach for headless WordPress. If you need a refresher on what this site development methodology looks like, check out this resource on headless WordPress.
Common Reasons to Use Headless WordPress
Improved Performance and Perceived Performance
When asked about their plans to transition to a headless CMS, many developers cite performance as a key driver for that decision. While actual performance is important to popular site ranking metrics, many modern JavaScript frameworks can provide perceived performance benefits as well, meaning that sites feel faster and more responsive to users even though that may not be the case.
Load Fewer Assets with Code Splitting
In traditional WordPress, CSS and JavaScript code are typically enqued across an entire site without convenient methods to decide when and where to load particular assets. In some cases, WordPress decides for you what libraries to include (we’re looking at you jQuery).
Modern JavaScript build practices and frameworks utilize various approaches to code splitting, which helps you load only the code that is required to render a particular page, view, or component. The goal of code splitting, whether route-based or component-based, is to lower the size of the initial payload that the user has to download.
Less code shipped to the browser means less bandwidth and less time spent parsing and executing JavaScript that isn’t required for the current page. All of that makes your site more performant on less powerful mobile devices or devices with a slow connection.
While there are certainly ways to optimize your assets using traditional WordPress through caching, minification, and other optimization techniques, the tooling available in JavaScript frameworks gives developers some additional methods to tackle performance issues.
Faster Page Transitions
If your chosen frontend framework supports client-side or hybrid routing, you can create extremely fast page transitions since your app is only loading and re-rendering the parts of the page that have changed. While the actual load time of a client-side page navigation vs. a statically generated and heavily cached page may not differ substantially, this is an example of where a user could perceive client-side routing as more performant because they don’t experience the visual interruption of a full page refresh as they browse the site.
Improved Core Web Vitals
When using pre-packaged themes for traditional WordPress, it can be difficult to achieve healthy scores on Core Web Vitals without lots of customization by a developer. These metrics are described by Google in the guide on Web Vitals:
“Core Web Vitals are the subset of Web Vitals that apply to all web pages, should be measured by all site owners, and will be surfaced across all Google tools. Each of the Core Web Vitals represents a distinct facet of the user experience, is measurable in the field, and reflects the real-world experience of a critical user-centric outcome.”
Philip Walton, Web Vitals
Core Web Vitals include things like Largest Contentful Paint (LCP), First Input Delay (FID), Cumulative Layout Shift (CLS), which all address important aspects of how performant and usable web pages are as they load on user devices. Most frontend frameworks come designed to address many of these vital site metrics, and improved Core Web Vitals is one common benefit of adopting a headless architecture.
Total Rendering Control (SSG/SSR/CSR)
In the world of the web, everything eventually comes full circle, including patterns of rendering sites in the browser, or the process of translating your data and component tree into the HTML, CSS, and JavaScript that browsers can understand and display. Over the last several years, this area has seen massive technical innovation along with whiplash-inducing changes in opinion on ‘best practices,’ from rendering on the server, to rendering everything on the client with SPAs, to pre-generating static HTML files using static site generation (SSG).
While there isn’t enough room in this post to look at all of the rendering patterns in detail, WordPress’ method of server-side rendering (SSR) hasn’t changed at all during that period, which is a testament to the stability of its core platform. However, one of the chief benefits of the headless approach is that teams can adopt WordPress as a stalwart CMS, while also taking advantage of the innovation happening alongside popular frontend frameworks to create best-in-class experiences for both the creators and consumers of digital content.
Improved Developer Experience
In the broader community of web and software developers, we see the rapid creation of new technical patterns, tools, and methodologies that as a whole move the industry forward. Yet, in many ways, WordPress’ core software seems to take the opposite approach and prioritizes stability over constant reinvention. As a result, many developers have to reconcile two different approaches to development that feel out of step with one another. In many ways, adopting WordPress as a headless CMS can help bridge this gap, pairing a stable and trusted open source CMS with a JavaScript environment that lends itself to rapid innovation.
Component-based Architecture
One of the characteristics of most JavaScript frameworks is that they lend themselves to component-based design and development. When compared to traditional WordPress theme development which centers around PHP page templates and perhaps partials that are created from repeated components, component-based development offers many benefits to large teams and enterprises where this headless site will be only one piece of a larger ecosystem of properties tied to a specific brand.
For example, let’s imagine a SaaS company that has invested heavily in building out a brand compliant component library for their flagship product. By adopting a headless architecture, their development team is able to reuse code and components across multiple web properties, thus speeding up development time and ensuring brand consistency.
Leverage the JS Ecosystem
Just like the ecosystem for WordPress themes and plugins, the JavaScript ecosystem is equally diverse. By building on modern web development tools, you gain access to a variety of new components that can enhance the quality of your site and the user experience.
While the WordPress plugin repository helps traditional users accomplish these goals, the choices available can be limited if we are looking for very specific functionality. For developers, using the REST API or GraphQL API to integrate with WordPress can remove some of the overhead associated with creating a traditional plugin, especially if the scope and configurability of the component is limited.
This can be a huge productivity boost depending on the skills of your development team, but if you need to rely on individual WordPress plugins for specific functionality, not all of them are built to support the REST API or GraphQL. The headless community has worked hard to create extensions to popular plugins that allow them to more seamlessly integrate into decoupled frontends, so be sure to conduct a thorough needs assessment of your required functionality before starting a new headless project.
Flexible Data Sourcing
Perhaps the most compelling reason to consider WordPress as a headless CMS is the flexibility of data sourcing. While WordPress is sometimes known primarily as blogging software, it also has the ability to extend its basic type system to create complex types, relationships, and hierarchies. Making this data available via REST or GraphQL APIs gives organizations a ton of flexibility in how they construct and populate data stores.
Write Once, Publish Everywhere
One of the most important features of a headless CMS is that they enable omnichannel experiences, meaning your single CMS provides the same data to your website, other clients like iOS or Android apps, or Internet of Things connected devices. WordPress comes with a robust REST API out of the box that is powering more and more critical experiences on the platform, but using plugins like WPGraphQL you can also turn your WordPress site into a powerful GraphQL API to gain the performance benefits of that technology.
Ingest Data from Multiple Sources
Headless architecture allows you to easily combine your WordPress source data with data from other APIs to provide richer customer experiences. Depending on your frontend application choices, you may have some flexibility in how you do this. For example, if you are building a Next.js application, you could write code in getStaticProps or getServerSideProps hooks that queries both your WordPress API (GraphQL or REST) in addition to the other services required to produce a particular page. On the other hand, you could also extend WordPress using a plugin to create a custom REST endpoint in PHP that gets added to your WordPress site’s existing API or GraphQL schema. If your site will end up displaying data from a variety of sources and WordPress is one of them, then that could be a good reason to pursue a headless architecture.
Model Complex Data Types
Although WordPress has a great reputation as a tool for personal blogs or small websites, it is also a powerful CMS that can be extended to model complex types of content. While many organizations have taken advantage of that feature in traditional WordPress PHP templates, the data can also be exposed via API to be used on any publishing channel. In the past, creating these complex data types required either a collection of related plugins or lots of custom code, but Atlas Content Modeler provides an integrated approach to both managing custom content types and making them available to decoupled clients.
Increased Security
Over the years, WordPress has gotten what is perhaps an unfair reputation for bad security practices, which becomes a common objection to using it in favor of other CMSs. However, one of the benefits of decoupled systems is both a separation of concerns and system resiliency, both of which help to create more secure environments.
Reduce Surface Area for Attackers
Since the backend WordPress instance isn’t available to the public in headless deployments, it is more difficult for bad actors to target that instance specifically. In many cases, it can be impossible to tell that a headless site is using WordPress at all since there are no public artifacts in the source code or network calls that give away this information unless your client-side code connects directly to your WordPress instance.
Importantly, if a hacker can’t tell you are using WordPress, they won’t know to try any WordPress-specific exploits. Additionally, since many headless deployments are less reliant on themes and plugins, they become more secure because outdated themes and plugins are most often the source of vulnerabilities rather than the core WordPress software itself.
Additionally, since the frontend application and CMS are now decoupled, you could apply advanced networking techniques to promote security. For example, you could disallow traffic to your CMS from IP addresses outside of an approved list that includes your corporate office and frontend app, that way you have complete control over the connections made to your CMS.
Possible DDoS Resiliency
Since the system that renders your content (e.g. your frontend app) is separate from the system that stores and manages it (e.g. WordPress CMS), you gain an amount of resilience in the face of a Distributed Denial of Service attack. In many cases, a DDoS attack has the potential to take an entire traditional CMS offline, meaning both the user-facing site and the administration panel will be taken offline. While there is no guarantee that a headless site won’t experience a total outage as well, some of the patterns used to develop headless frontends, like static site generation, help to mitigate the load across the system.
When Should I Use Traditional WordPress Instead?
Even though there are lots of use cases that support adopting a headless architecture using the WordPress CMS, there are still very clear cases where it makes more sense to deploy a traditional WordPress site. Let’s take a look at some of those reasons, below.
Clients Expect to Take Advantage of Certain Traditional WordPress Tools and Features
One of the reasons WordPress has grown so dominant in the CMS marketplace is because of how easy it is for a user to customize their site on their own using plugins, theme customizations, or other types of page builders. In a headless approach, the data stored in the CMS is separated from its presentation to the user.
In practice, this means that most visual enhancements that get applied to a page or component via plugins, custom blocks, or page builders will not get displayed by default in a headless deployment. When starting a new project or talking with a potential client, understanding their expectations around their ability to change or customize the site design will be an important indicator of which approach is best suited to their needs. Here are just a few indicators that a traditional WordPress installation might be best:
You Want to Use Full Site Editing Capabilities
One of the latest changes to traditional WordPress is the addition of full site editing capabilities to the WordPress admin area. The goal of this change is to bring the capabilities of many page builder plugins/themes directly into WordPress core through things like block themes and block patterns. This new paradigm gives site users a far greater depth of control over the visual output of a site without having to dive into code.
In many ways headless WordPress and full site editing exist on opposite ends of a spectrum. On one end you have headless WordPress, where WordPress merely acts as a data repository for your site content, and on the other end full site editing allows users to more fluidly compose site elements using blocks and block patterns. If you or your client wants to be able to use full site editing features, sticking with a traditional WordPress installation might be your best bet.
You Need Plugins for Visual Site Components
Given the specific requirements of headless WordPress, some plugins may not work well in this environment out of the box. For example, any plugin that adds visual output to a post or page will most likely not display correctly without additional configuration. If we use a traditional carousel plugin as an example, these types of plugins typically output an HTML structure to the post content and enqueue additional CSS and JS assets to style the page and make it interactive. When getting the post content through the REST or GraphQL API, we only have the HTML content to work with, leaving the developer to recreate or port over the CSS and JS needed to make the carousel function properly.
If you know that your development team will need to use plugins to create site components or that the client expects to add plugins on their own to customize the site visuals, that is a good signal that a traditional WordPress installation is likely best for your project.
Overall Cost or Project Timeline Prohibit Headless
Even though there are many benefits of using the WordPress CMS as the backbone of a headless architecture, just the nature of creating a decoupled application means that it comes with additional technical complexity that should be considered. Unless you or your agency specialize in headless application development, developing a headless website may require additional labor to actually deploy and additional maintenance cost to keep updated. A platform like Atlas can help offset some of these costs by giving development teams one central place to develop, deploy, and maintain headless sites, but other hosting providers can leave your resources scattered across a number of other services.
Often project timeline and overall cost are evaluated against some of the benefits that a headless architecture may provide, and not every client may be willing and able to make those trade-offs. If this is the case, a traditional WordPress approach may be best.
Your Developers Aren’t Fluent with Tech Required for Headless
While traditional WordPress offers the promise of no-code or low-code website development, headless WordPress relies on developers skilled in the technologies required to deliver content to your particular channel. For the web, that skill set typically involves an intermediate to advanced understanding of modern JavaScript frameworks like Vue, React, Svelte, or Angular, experience consuming data from REST or GraphQL APIs in that given framework, and other frontend related technologies like HTML, CSS, and web accessibility.
Depending on your chosen deployment location, you may also require developers with a backend focus that have experience developing custom REST API endpoints in PHP or modifying the GraphQL API schema. However, WP Engine’s Atlas platform helps abstract away some of the configuration details needed to create and extend the CMS administration and authoring experience.
Regardless of your hosting environment, your developers will need to also be skilled in using GitHub to manage codebases, as most headless hosting environments use this strategy to manage deployments.
Wrapping Up
Throughout this blog post, we’ve discussed several key scenarios where we should consider using WordPress as a headless CMS. When compared to traditional WordPress deployments, headless approaches have the following potential benefits:
- Improve actual performance and perceived performance by adopting innovations happening in the frontend framework space
- Create more enjoyable and productive patterns for developers
- Serve complex data to omnichannel clients using REST or GraphQL APIs
- Provide increased security and system resilience
However, it’s also important to consider other factors for when a traditional WordPress deployment might be right for you or your client:
- The client expects to have some element of visual, aesthetic, or functional control over the site through affordances in the WordPress dashboard (e.g. plugins, page builders, custom blocks, theme customizer options)
- The overall cost or timeline of a headless deployment is prohibitive to you or your client
- You or your developers aren’t fluid in the tech required to manage or create headless experiences
At the end of the day, one of the reasons WordPress has gained such widespread adoption as a platform is because of the almost infinite ability to offer more options. In this way, adopting WordPress as a headless CMS is just another option that you have as a developer when the challenges you are facing could be solved by taking a headless approach.
