A Retrospective on 4+ years of Faust.js

Hello! It’s been a while since we posted (our bad).

Many of you have asked for updates, and we’re ready to discuss what’s going on with Faust and WP Engine’s contributions to the headless WordPress ecosystem.

TL;DR

Times are changing, and after reflecting on 4+ years of building Faust and contributing to the headless WordPress ecosystem, we’ve got a clear vision of how to move forward. We’re looking forward to building better documentation and code that’ll empower developers to learn headless WordPress and grow with them as their knowledge, experience, and needs evolve.

The Headless Open Source team is actively refocusing our efforts while ensuring we’re building in a way that’s useful, sustainable, and inclusive of a growing community.

A big aspect of sustainability is making this a community effort, not a WP Engine-dependent project. Because of this, our team will do all our work publicly on GitHub issues and PRs.

Additionally, we’ll be engaging more on the Headless WP Discord and holding public meetings to hear from the community and set priorities. Please feel free to reach out on Discord or GitHub with questions or if you’d like to contribute.

This new focus means our team is actively working to reduce distractions. With that in mind, we’re announcing some changes of status for existing project maintenance:

New https://toolkit.faustjs.org website

Early Access, the new site will replace the existing one by the end of February

Heavy investment in the quality of documentation

Repositioning of Faust.js as a “Toolkit for Next.js,” not a framework

Immediate deprecation of experimental Faust.js features

Admin Toolbar

App Router Support

The Team

The team that maintains Faust.js is going through an overhaul in various ways. Notably, we’re no longer a WP Engine product team (don’t worry, we still work for WP Engine).

Product teams are great for paid products, but we have come to realize that open-source software (OSS) projects must be treated differently. The old team was only responsible for Faust.js, and this disconnected them from much of the other open-source work being done.

WP Engine has corrected this by creating the new Headless OSS team. These team members are positioned to be maintainers, stewards, and contributors working to make WordPress the best headless CMS available.

WP Engine has contributed to this effort through various projects, such as wp-graphql-smart-cache, wp-graphql-ide, wp-graphql-content-blocks, Faust.js, and WPGraphQL, and this work will continue under the new team.

The Headless OSS team will work in public and directly engage with the community that builds with headless WordPress. Our goal is to invest in WordPress and the WPGraphQL ecosystem to make WordPress the best headless CMS.

Vision

This new team has spent the last quarter reflecting on the 4+ years of history behind Faust, including the vision, the assumptions, the failures, the successes, and how the headless WordPress ecosystem has changed around it. We’ve heard a lot, but above all, we now understand the headless WordPress community needs more than just code solutions.

Code is, by nature, targeted at a very specific demographic of developers and use cases. It can serve this group well, but for developers with different needs and use cases, code will fail to serve them, and can even become a hindrance rather than a help.

For WordPress to become the headless CMS of choice, it will take more than just some code. It will require three things: code, tooling, and documentation.

Historically, we’ve shipped lots of code, little documentation, and no tooling. Going forward, tooling and documentation will be seen as equally, if not more, important.

Goal

Long, long ago, in a company far away, the vision for Faust.js was to be the “Next.js of headless WordPress.” This monolithic attitude meant we built solutions that were tightly coupled.

We shipped the FaustWP plugin and the @faustwp/core NPM package, and they only worked with each other using Next.js and React. Other technology decisions were made similarly. For example, when Faust needed authentication, our implementation was tightly coupled. While someone could theoretically reverse engineer the implementation and leverage it elsewhere, this is just not realistic.

In contrast, we see WP Engine’s contributions on wp-graphql-smart-cache as a great example of how we could move forward.

In collaboration with Jason Bahl and our own platform developers, a plugin was developed that brought world-class caching mechanisms to WPGraphQL. In contrast to the tightly coupled nature of Faust.js, Smart Cache implemented powerful tooling and defined APIs so that any hosting provider or GraphQL client could support it.

Moving forward, the Headless OSS team at WP Engine will use this example as inspiration for delivering better software—software that’s modular, adaptable, and (hopefully) simple.

Instead of dependency-heavy end-to-end solutions, we’ll create strong APIs that everyone in the headless WordPress community can leverage. These will be targeted plugins and packages that can be used as needed, not one monolithic solution.

So, Faust.js?

The first step is to reposition Faust.js as a “Toolkit,” not a “Framework.” The work on this has been headed by the WP Engine Developer Relations team and the preview of the new faustjs.org site and documentation can be found at https://toolkit.faustjs.org. This will go live to the main URL as soon as we put some finishing touches on the documentation.

As the Headless OSS Team looks forward and evaluates Faust.js, we’re deprecating experimental features. Due to the lack of Apollo support for the Next.js app router, there’s little purpose in our continued maintenance of this experiment. Full details, along with archived code and documentation, can be found in the Faust repository.

The Admin ToolBar is an example of how we’ve unintentionally overcomplicated things in Faust. Due to its experimental nature, we’ll be deprecating it to free up resources and invest in other aspects of Headless WordPress.

If there are bugs you need fixed, we’d recommend leveraging patch-package or copying the source code for the components directly into your project. The code enabling this feature will not be removed from the @faustwp/core package or the FaustWP plugin.

What’s Next?

We’re not done. We’re here to tell you we’re working hard as ever to help make WordPress a great headless CMS. We hope to accomplish this through various projects and OSS contributions.

For example, the community doesn’t need Faust’s specific authentication implementation. Since we built it, our friend and avid OSS contributor David Levine built wp-graphql-headless-login. A well-documented and standardized authentication plugin for the WPGraphQL community to use. Moving forward, we will work with Levine and the community to maintain and improve wp-graphql-headless-login, and any packages, documentation, or tooling we build will use that quality plugin.

Additionally, Levine has been working with us and contributing to wp-graphql-content-blocks to help us improve its implementation. This will bring vast improvements in performance and the usability of WordPress Blocks and Full Site Editing.

We invite you to join us

These are just a few of the ideas we’ve had about improving Faust.js and headless WordPress. We invite you to follow along and contribute to this future we’re building.

We have a new repo where we’re experimenting and researching. Follow along on the Faust repo for news specific to Faust.js.

We mentioned earlier that the Headless OSS team aims to work publicly and engage directly with you, the developers who build and rely on headless WordPress. With that in mind, we invite you to collaborate with us. There are several ways you can do so:

The new Headless WordPress Toolkit repository

The Faust.js repository

Join us at our twice-monthly headless WordPress community meetings

Join our Headless WordPress Discord