repository·canary·Indexed 23 days ago
https://github.com/wpengine/faustjsA toolkit for building Next.js applications for headless WordPress sites. Faust.js provides specialized tooling for data fetching, authentication, previews, and rendering strategies (SSR and SSG). The ecosystem includes @faustwp/core, @faustwp/blocks for Gutenberg block rendering, @faustwp/block-editor-utils for converting React components into blocks, and the @faustwp/cli for application management.
Faust.js is a toolkit designed for building Next.js applications for headless WordPress sites. It provides specialized tooling to address common challenges in headless WordPress development, specifically around:
It aims to provide a high-quality experience for both developers and content publishers.
@faustwp/cli package provides a command-line interface designed to help developers develop, build, and serve Next.js applications built using the Faust.js framework.When rendering blocks in Faust.js, there is a three-part relationship between the block components, the GraphQL fragments, and the rendering components:
wp-blocks/index.js). This is passed to WordPressBlocksProvider..fragments.entry property of each block object in your GraphQL query to fetch the required fields. You also use .fragments.key to spread the fragment into the editorBlocks selection set so the data is available for the component.flatListToHierarchical to reconstruct the tree structure before passing it to WordPressBlocksViewer.The Faust Plugin System uses a filter pattern to allow developers to intercept and modify core system data.
Every filter callback accepts two parameters:
To use these filters, you typically use the addFilter method within a plugin's apply method.
The WP Template Hierarchy allows you to define individual components for specific WordPress templates. These components are rendered automatically based on the route being visited. Common templates include:
front-page.js: For the site's front page.single.js: For single posts.page.js: For static pages.category.js: For category archive index pages.You can check the browser dev console when visiting a page to see which templates Faust might match for that route.
The Seed Query is an initial GraphQL request sent to WordPress to determine the type and basic properties of the content requested via a URI. It does not fetch the full content itself; instead, it provides the metadata necessary for faust.js to determine which template to render.
/sample-page/).SEED_QUERY to WordPress.__typename and essential properties (like templateName or contentType).The seed query utilizes WpGraphQL's nodeByUri for standard requests and contentNode for preview requests ($asPreview: true). It uses several fragments to ensure the response structure adapts to the content type (e.g., Post, Page, User, TermNode, MediaItem).
// Example of the SEED_QUERY structure used by faust.js
export const SEED_QUERY = gql`
query GetSeedNode(
$id: ID! = 0
$uri: String! = ""
$asPreview: Boolean = false
) {
... on RootQuery @skip(if: $asPreview) {
nodeByUri(uri: $uri) {
__typename
...GetNode
}
}
... on RootQuery @include(if: $asPreview) {
contentNode(id: $id, idType: DATABASE_ID, asPreview: true) {
__typename
...GetNode
}
}
};When fromThemeJson processes a theme.json file, it transforms nested settings into top-level properties on the BlocksTheme object for easier access.
| theme.json Path | BlocksTheme Property |
|---|---|
settings.color.palette | theme.palette |
settings.spacing.spacingSizes | theme.spacingSizes |
settings.typography.fontFamilies | theme.fontFamilies |
settings.typography.fontSizes | theme.fontSizes |
settings.layout | theme.layout (copied as is) |
Input theme.json snippet:
{
"settings": {
"color": {
"palette": [
{ "color": "#ffffff", "name": "Base", "slug": "base" },
{ "color": "#000000", "name": "Contrast", "slug": "contrast" }
]
}
}
}Resulting BlocksTheme object:
theme.palette = {
"base": "#ffffff",
"contrast": "#000000"
}The styles/wpcore directory contains stylesheets ported directly from WordPress core. These styles are intended to provide the standard WordPress look and feel for specific elements (like the admin bar and dashicons) within the Faust.js environment.
Important: These stylesheets should remain untouched to ensure compatibility with the original WordPress core design and functionality.
The default authentication strategy in the Faust.js toolkit is Redirect-based authentication. This is ideal for use cases where authenticated users are admins, editors, or staff (e.g., for previewing posts/pages) and do not require a custom "white label" login experience.
The Flow:
Faust.js uses @apollo/client@3 to perform GraphQL operations against your WordPress backend. To work effectively with Faust.js, you should be familiar with the following core Apollo Client concepts: