Headless WordPress and Faust.js: benefits and set up

Headless WordPress development is a rising trend in a software development industry that’s steadily moving toward headless CMS architectures, but some consider the current solutions to be a bit rough around the edges.

Faust.js is a headless WordPress framework launched by WP Engine that aims to simplify the process and enhance the developer experience. By leveraging React and Next.js, Faust.js provides a comprehensive set of tools to address common challenges faced by developers when setting up a headless WordPress architecture.

With features such as efficient data fetching, native post previews, and leveraging the WordPress template hierarchy, Faust.js is positioned to become the go-to framework for developers working with headless WordPress implementations. Let’s explore its benefits and how to set it up for your project.

What is headless WordPress?

Headless WordPress is using WordPress with a headless rather than monolithic architecture. WordPress and other content management systems (CMS) traditionally pack the backend and frontend into a single software for managing a site’s content. The backend combines the databases and server(s) that make the site work, and the frontend is the user-facing part of the website, which users see and interact with when they visit.

The headless architecture changes this model by decoupling the backend from the frontend. The CMS acts as the backend, connecting to a different platform to display user-friendly interfaces and content on the frontend. Some of the most popular frontend technologies developers use for headless implementations include React, Next, Vue, Angular, and Gatsby.

Under this model, WordPress becomes a content hub, exporting data to the frontend by exposing an application programming interface (API) that any frontend technology can use.

Headless WordPress is a relatively new offering. However, it’s already garnering attention for its potential to provide developers flexibility in their frontend choices and the scalability of managing multiple channels from the same backend.

What is Faust.js?

Faust.js is a headless WordPress framework launched in late 2021 by the managed WordPress hosting company WP Engine. It provides the tools to simplify the process of building front-end apps using WordPress as the headless backend, improving the developer experience.

Built on top of Next.js, Faust.js aims to solve many of the problems developers face when setting up a headless WordPress architecture, namely previewing content, authentication, fetching data, server-side rendering (SSR), and static site generation (SSG).

Previews, in particular, are one of Faust.js’ major advancements. It’s been traditionally challenging to preview content in headless WordPress implementations, but Faust.js provides native preview from the backend, making the publishing experience closer to traditional monolithic WordPress.

With this and other features, Faust.js provides developer-friendly helper functions and APIs that save time when building the structure of a headless project, aiming to become the #1 framework for headless WordPress developers using any front-end framework.

What are the benefits of Faust.js?

Efficient data fetching

The original Faust.js version launched in late 2021 went through significant changes throughout 2022. One of the major changes included switching from GQty to Apollo as the chosen GraphQL client, primarily due to debugging limitations and developer expectations.

Apollo is a state management GraphQL client for managing local and remote data. Additional features include error handling, pagination, caching mechanisms for minimizing unnecessary network requests, data prefetching, React Hooks integration, and more. Apollo simplifies working with GraphQL in JavaScript frameworks, simplifying headless WordPress development in the process.

Previewing posts

Faust.js natively supports page and post previews, so publishers can view their content on the frontend as drafts without developer intervention. After the initial setup, all page and post preview links on the admin dashboard work just as they normally would on traditional, monolithic WordPress.

Template hierarchy

The template hierarchy is the logic and structure that WordPress web apps use to determine which template file to use for rendering a specific page or post on a website. Traditionally, headless WordPress developers have to spend a lot of time wiring up individual routes to match the appropriate templates with specific content, often experiencing difficulties with complex routes.

Faust.js solves the problem of relying on customized routing solutions by leveraging the WordPress template hierarchy to determine whether WordPress manages a GraphQL request’s URI. This information helps developers decide the type of template that should render the content. 

This preliminary GraphQL request is called a “seed query,” to which WordPress responds with slug, databaseID, and other information. This information helps determine which template(s) correspond to a given URI, without bespoke routing. The seed query looks something like this:

{

  "data": {

    "node": {

      "__typename": "Page",

      "uri": "/sample-page/",

      "id": "cG9zdDoyNjQ=",

      "databaseId": 264,

      "isContentNode": true,

      "slug": "sample-page",

      "contentType": {

        "node": {

          "name": "page"

        }

      },

      "template": {

        "templateName": "Default"

      },

      "isFrontPage": false,

      "isPostsPage": false

    }

  }

}

Extensibility

WP Engine understands that one of WordPress’ most powerful features is its plugin ecosystem and decided to make Faust.js extensible, letting developers create their own custom functions.

Essentially, Faust plugins are JavaScript classes with an apply method that contains a parameter called hooks, which is passed from @wordpress/hooks. The following is an example of a plugin in TypeScript:

import { FaustHooks, FaustPlugin } from '@faustwp/core';

export class MyPlugin implements FaustPlugin {

  apply(hooks: FaustHooks) {}

}

For a real example, check out this plugin by Jason Bahl, WPGraphQL creator and maintainer. It adds Automated Persisted Query support.

How to set up Faust.js for your headless WordPress implementation

To start building headless WordPress sites with Faust.js, run the following code in a directory of your choice:

npx create-next-app \

    -e https://github.com/wpengine/faustjs/tree/main \

    --example-path examples/next/faustwp-getting-started \

    --use-npm

It’ll likely take a couple of minutes. Once preparations are complete, move to your new project at my-app and copy the sample environment template:

cp .env.local.sample .env.local

Now run the dev server:

npm run dev

Your project is now located at http://localhost:3000 and is loading posts and pages from WP Engine’s example site. To connect your Faust.js project to a specific WordPress site, first ensure you’ve installed and activated the WPGraphQL and Faust.js plugins. Once installed, open the .env.local file from the earlier steps. Here’s how it looks by default:

# Your WordPress site URL

NEXT_PUBLIC_WORDPRESS_URL=https://faustexample.wpengine.com

# Plugin secret found in WordPress Settings->Headless

FAUST_SECRET_KEY=YOUR_PLUGIN_SECRET

Replace https://faustexample.wpengine.com with your site’s URL (including the https://) and YOUR_PLUGIN_SECRET with the secret key you’ll find at in Settings > Faust in your WordPress admin dashboard. You need to input the secret key to support post and page previews.

Now it’s time to set your frontend site’s URL. Go to your Faust.js plugin settings and input the URL in the Front-end site URL field. It can be a live URL or http://localhost:3000. This step also ensures you can use the post and page preview feature.

Finally, go to Dashboard > Settings > Permalinks. Navigate to the Common Settings section and ensure it’s not set to Plain. You can choose any other setting except Plain.

And you’re done! You can now start editing your headless WordPress site using Faust.js.

Faust.js makes headless WordPress development less daunting

Faust.js is a JavaScript development framework specifically designed for creating flexible, fast, scalable, and extensible headless WordPress websites. It allows developers to build modern and highly interactive user interfaces using web technologies such as React and Next.js, connected to the WordPress backend through a GraphQL API.

Despite being quite new, Faust.js is starting to stand out as one of the premier headless WordPress solutions due to its seamless integration with WordPress, focus on component-based development, high performance, and flexibility to use any frontend technology.

If you’re interested in headless WordPress, check out our blog for more tips, guides, and insights!