A Quick Guide to Headless WordPress

A headless WordPress system helps web designers and developers work on their sites more efficiently. However, if you’re new to this concept, you may struggle to understand how it works. Moreover, you might be wondering whether it’s the right solution for your project. 

That’s why we’ve created this quick guide to headless WordPress. By deep-diving into the world of backend-only content management systems (CMS), you can decide whether a headless setup is the right fit for your web development projects. 

In this post, we’ll take a closer look at headless WordPress, and discuss its pros and cons. We’ll then show you how to get started with it and review a few tools that you can use. Let’s jump right in!

An Introduction to Headless WordPress

Most CMSs have a front-end and a back-end. With a WordPress site, the back-end consists of the admin panel and content management tools:

WordPress dashboard

Meanwhile, the front-end is everything that visitors see when they arrive at your website. Typically, this content is rendered by your active WordPress theme:

WordPress test site homepage

When you run WordPress headless, you remove the head (front-end) from the body (the back-end). This way, you can continue to use the familiar dashboard, while freeing yourself from the platform’s front-end constraints. 

In a headless setup, the WordPress CMS provides your content as data using a representational state transfer (REST) application programming interface (API). You can access this information by sending a network request to WordPress’ built-in REST API endpoint. This gives you the freedom to present all of this content in a custom front end. 

You can even use your WordPress data in unique contexts, including mobile applications and single page applications (API). In the next section, we’ll take a closer look at the benefits of running a headless system.

Why You May Want to Run WordPress Headless

It’s not unusual to reuse the same content across multiple platforms. For example, eCommerce giant Amazon operates an online store and a dedicated mobile application. These two channels display the same content:

Amazon's Shop Toys & Games page

Using the headless eCommerce setup, you can use the exact same data across several platforms. This makes it easier to maintain an active presence on multiple channels.

Your headless WordPress also acts as a central repository. This can ensure consistency across all of your platforms. It also means that you’ll only need to edit your content once, and that change will then be replicated on different channels. 

Since headless content is delivered over an API, you’re free to use your preferred front-end tooling. If you choose a tool that you’re already familiar with, this can help you reduce the amount of time you spend designing and developing your pages.

As your project evolves, you may need to adopt new tools, or switch to alternative technology. The good news is that you can change parts of your headless stack or move to an alternative framework without it impacting your CMS. This enables you to continuously adjust your project in order to meet your evolving needs.  

This flexibility isn’t limited to the back-end. By cutting away the WordPress front-end, you also eliminate your reliance on themes and plugins. 

WordPress may have a huge ecosystem of third-party software, but themes and plugins are still restricted by the conventions of the platform’s front-end. By removing these limitations, you’ll have far greater control over your content’s appearance and your site’s functionality. 

Potential Issues With Headless WordPress

Headless WordPress gives you more design and development freedom. However, this flexibility comes at a cost. 

Building your own front-end can be a time-consuming and frustrating process. It also requires a significant amount of technical know-how, and may involve writing extensive code. 

There are WordPress frameworks and tools that can perform much of the heavy lifting for you. However, building your own front-end is a bit more complex than using WordPress’ ready-made tools. 

Even when your site is up and running, a headless WordPress site usually requires more ongoing maintenance. Since you built the front-end manually, you’ll also have to implement any changes manually. This includes publishing new content and editing your site’s design. 

Themes and plugins are a big part of the WordPress experience. By running this platform headless, you immediately lose access to all of this additional software. If you want to add a new feature or change your design, you’ll need to code it into your project manually. 

Unless you develop your own solution, headless WordPress doesn’t offer a What You See Is What You Get (WYSIWYG) editor or live preview option. This can make it difficult to judge how your content will appear on the front-end. 

How to Get Started With Headless WordPress (2 Methods)

We’re not going to pretend that building your own front-end is straightforward. However, there are tools that can help make this process easier. 

With this in mind, let’s explore two ways to set up a headless WordPress project with minimum hassle. 

Method 1: Use a Framework Like React

Building a front-end for the WordPress CMS can be a time-consuming and complex task. For this reason, many developers choose to use a framework. 

You can build a custom WordPress front end using the React JavaScript library. This popular resource has everything you need to access the data stored in your CMS via the WordPress REST API:

React homepage – A JavaScript library for building user interfaces

The React framework also promises to supercharge your headless project by eliminating the need to re-render. This means that your project’s fundamental code is loaded just once. 

If the state of a component changes, the React framework will only re-render the affected content. This makes React-based frameworks particularly popular among developers who are planning to build a SPA. 

Originally launched for use with Facebook, many big names have now embraced this popular technology. This includes Airbnb, Dropbox, Netflix, and Reddit. 

With backing from so many multinational companies, it’s not surprising that React has extensive online support, including official documentation and helpful tutorials:

React Getting Started page, featuring its documentation and related tutorials

If you encounter an issue, you should have no problems finding relevant answers and solutions. This is great news for anyone who is exploring React for the very first time, or is new to frameworks in general. 

While you may opt to use the React library, there are also a number of React-based frameworks you could use. This includes the Frontity project, which is pre-configured to provide the best possible experience for WordPress users:

Frontity homepage – The React framework for WordPress

Other popular React-based frameworks include the Gatsby.js open source project and Next.js by Vercel. With so many options to choose from, you can shop around and find the best fit for your particular project. 

Method 2: Use a Plugin

With WordPress, there is a plugin to help you accomplish almost any task. When it comes to configuring headless WordPress, there are a few good options that can help you get started. 

Let’s take a look at two powerful plugins that you can use.

1. WPGraphQL

WPGraphQL Banner

WPGraphQL is a free plugin that’s designed to help you fetch data from headless WordPress. This plugin ships with the GraphQL integrated development environment (IDE), which enables you to browse your project’s GraphQL scheme and test queries and mutations.

Under the hood, WPGraphQL transforms your WordPress site into a GraphQL API. This means that you can interact with this plugin using any client that’s capable of making HTTP requests to the GraphSQL endpoint. 

WPGraphQL is designed to be used with frameworks such as Apollo Client, Next.js, and Gatbsy.js. If you’re using Gatsby, you may want to check out the Gatsby source plugin for WordPress

With this source plugin, you can perform fast incremental builds and preview the content in your CMS. For this reason, you may want to opt for WPGraphQL if you’re planning to use Gatsby.js.

Key features: 

  • An extendable GraphQL schema and API for your WordPress website
  • Access to multiple root resources
  • The ability to follow references between connected resources
  • Extensive documentation

Pricing: You can install this plugin for free.

2. CoCart – Headless eCommerce 

CoCart banner on WordPress

Online shopping has evolved from something that’s performed purely on computers. During the third quarter of 2020, smartphones generated 56% of online shopping orders in the US. This explains why we’re seeing so many online stores creating mobile applications.

If you’re launching an online store across multiple platforms, you may want to use a solution such as WooCommerce as part of your headless setup. However, WooCommerce doesn’t come with cart support via the REST API by default. 

This is where CoCart comes in. This free plugin provides an API that enables you to access the WooCommerce cart as part of your headless setup. It also supports customers who want to check out as a guest, and is capable of performing basic authentication. 

If you’re an admin or shop manager, you can use this plugin to view carts in session, including the products that customers have added to their shopping baskets. This makes CoCart a highly recommended plugin for a headless eCommerce setup. 

Key features:

  • Add simple, variable and grouped products to the WooCommerce cart
  • Update, remove, and restore items
  • Use the software across multiple domains 
  • Choose from over 100 CoGart filters and action hooks

Pricing: This plugin is available as a free download.

Best Practices for Headless WordPress

A headless WordPress site has lots to offer, particularly in terms of flexibility and reusability. However, there are some steps you can take to get the most out of your new headless setup.

Traditionally, WordPress website owners manage their site’s search engine optimization (SEO) using a dedicated plugin such as Yoast SEO.

However, headless WordPress doesn’t give you the plug-and-play simplicity you get from an SEO plugin:

YoastSEO's banner on WordPress – SEO for everyone

To ensure that your content ranks highly in search engines, it’s important to use a structured data markup scheme from Schema.org.

​​Schema markup provides a structure that helps search engines understand your content, and then rank it accordingly.

When used as a headless CMS, WordPress only requires a simple MySQL and PHP stack, making it a lightweight and high-performing option. However, there’s no such thing as content that loads too quickly. With this in mind, you can further improve your WordPress speed by using a content delivery network (CDN) to reduce latency.

It’s also important to optimize your WordPress images. You may want to use a compression tool such as TinyPNG. By making sure that all of your content is optimized for performance, you can help boost your already-impressive headless WordPress speed.

Conclusion 

Creating your first headless WordPress project can be a little challenging. However, with the right tools and WordPress website hosting, you can create a flexible, multi-platform headless setup without having to perform lots of heavy lifting.

In this post, we looked at three main tools to help you get started with headless WordPress:

  1. React-based frameworks: this includes frameworks such as Frontity, which was designed specifically for WordPress.  
  2. WPGraphQL: if you’re using the Gatsby framework, you may want to check out this free plugin. 
  3. Headless WooCommerce powered by CoCart: an eCommerce plugin that adds headless support to the WooCommerce cart. 

Do you have any questions about getting started with headless WordPress, or any of the tools discussed in this post? Let us know in the comments section below!

Author
The author

Will M.

Will Morris is a staff writer at WordCandy. When he's not writing about WordPress, he likes to gig his stand-up comedy routine on the local circuit.