Headless WordPress separates the content management system part of WordPress from the frontend presentation layer. Decoupling the front and back ends of your site allows you to leverage the power of WordPress as a content hub, while enjoying the flexibility and performance benefits of modern frontend frameworks.
In this article, we’ll discuss the tech stack you need, show you the first steps of setting up your headless environment, discuss some of the frontend frameworks available, and finally highlight some tutorials that show how to build various headless WordPress projects from scratch.
Most of what we’ll discuss requires that you have at least some knowledge of React. This video course is a great starting point.
Headless Use Cases
Before you start, it’s good to ask yourself if what you’re building actually needs to be headless at all. When Should I Use Headless WordPress? explores the pros and cons of using a headless WordPress architecture compared to a traditional WordPress deployment. It outlines several common reasons to choose a headless approach, such as improved performance, better developer experience, flexible data sourcing, and increased security.
The article also highlights scenarios where a traditional WordPress installation may be more appropriate, such as when clients expect to use certain WordPress tools and features, the overall cost or project timeline prohibits a headless setup, or the development team lacks the necessary skills for a headless implementation.
Building Your Headless Stack
At a bare minimum, you’ll need an API layer, a frontend framework, and a hosting platform. You’ll usually want a solution for building content models as well.
There’s plenty of choice when it comes to frontend frameworks. Popular choices include Gatsby, Next.js, Nuxt.js, and Faust.js. Each one has its own strengths and features, so it’s important to choose one that best fits your project requirements and development preferences.
The endless possibilities of headless WordPress may make it seem like you have endless choices to make. Headless WordPress Tech Stack Options lays out some of the options available and recommends a “happy path” for a headless development stack. We’ve summarized the recommendations below.
The Recommended Stack
WPGraphQL extends WordPress by supporting GraphQL requests, making it much easier to work with WordPress content in your frontend application.
ACF or ACF PRO, to build a source of structured data, including custom fields, custom post types, and taxonomies.
WPGraphQL for Advanced Custom Fields ensures the data created in ACF is accessible through the GraphQL API.
Faust.js provides a set of tools to enhance the headless WordPress development experience, including features like post previewing, authentication, and data fetching. This plugin helps you build the frontend of your headless WordPress site with the Faust.js framework.
Atlas allows you to host your WordPress backend and JavaScript frontend on the same platform and manage both from a single dashboard.
Advantages of Faust.js
Faust.js is an open-source framework developed by WP Engine, built on top of Next.js and React. Faust.js aims to simplify the process of building a headless WordPress site by providing a set of helpful features and APIs. The Faust.js documentation goes into the framework’s capabilities in detail, but the key benefits include:
Streamlined Data Fetching: Faust.js uses Apollo to handle data fetching from the WordPress backend, providing a more developer-friendly experience compared to the GQty GraphQL library used in earlier versions.
Template Hierarchy: Faust.js introduces its own take on the WordPress template hierarchy, allowing you to leverage your existing knowledge of WordPress theming to structure your headless application.
Plugin Architecture: Faust.js is extensible, enabling you to extend the framework’s functionality to fit your specific needs by creating custom plugins.
Authentication and Previews: Faust.js includes built-in support for both redirect-based and local-based authentication, as well as a seamless preview feature that allows content editors to visualize changes on the headless site.
Sitemaps: Faust.js helps manage sitemaps by proxying the sitemap index from your WordPress backend and integrating both file-based and CMS-based routes.
Check out “Get started with Faust” for an example project that will get you up and running quickly.
Faust.js and the Apollo Client
Faust.js uses the Apollo client to manage data with GraphQL. Working with the Apollo Client in Faust.js shows how to to fetch data from the WPGraphQL API and render it in your components and pages, how to implement cursor-based pagination and relay-style pagination, and how to create custom plugin filters to use these pagination methods in Faust.js.
Crash Courses and Tutorials
The tutorials below highlight different tools and approaches used in building headless WordPress sites.
Crash Course: Build a Simple Headless WordPress App with React & WPGraphQL shows you how to create a simple headless WordPress app using React and WPGraphQL. You’ll learn how to use the GraphQL IDE to compose GraphQL queries, use Apollo Client to fetch data in your app and render it to the page, and use variables in GraphQL queries.
Crash Course: Build a Headless WordPress App with Faust.js, WPGraphQL & Advanced Custom Fields teaches you how to create a headless WordPress app using Faust.js, WPGraphQL, and ACF. You’ll learn how to create custom post types and fields using ACF, fetch ACF data using GraphQL, and use Faust.js and Apollo Client to fetch and render the data in a decoupled Next.js app.
Headless WordPress with Nuxt 3 & Vue 3 shows how to build a basic headless WordPress site using Nuxt 3 and Vue 3. It covers starting a Nuxt 3 project from scratch, creating static and dynamic routes, using data fetching abstractions in Nuxt 3 to query and transform data from WPGraphQL, and deploying the Nuxt application to a Node.js server environment.
Building a Search Page with WP Engine Smart Search, Faust.js, and ACF in Headless WordPress teaches you how to build search functionality into your headless WordPress site using WP Engine Smart Search, Faust.js, and Advanced Custom Fields. You’ll learn how to configure a WP Engine Smart Search license, create custom post types and fields using ACF, run test queries using WP Engine Smart Search in the GraphiQL IDE, and build out a search page in your Faust.js app.
Conclusion
WordPress has always been highly flexible. Separating the CMS from the presentation layer increases this flexibility even further. The learning curve may be steep, but the resources we’ve presented here should be enough to get you started on your journey.
The tutorials we’ve highlighted are really just the beginning. We didn’t even touch on the rich possibilities of the App Router in Next.js 14 or Server-Side Rendering and React Server Components. Make sure to join the Discord for the latest information and discussions on headless WordPress,
Have you built a decoupled WordPress site or application? What did you use for the frontend? Let us know in the comments below.