Welcome to the world of Faust.js™! This tutorial will introduce you to the Faust framework as well as the complete cycle of application creation, configuration, and deployment as a developer of a Headless site using WordPress.

We make the assumption that you are comfortable with the command line and understand the basics of JavaScript, WordPress, and Bash. Since Faust is built on top of Next.js, we recommend having some knowledge of it as well.

• Quick Start
  • Installing Faust Framework
  • Installing Faust Plugin
  • Connecting Your WordPress Site
  • Set your Front-end Site URL
  • Check Your Permalinks
• Example Project Walkthrough
  • Understanding the Example Project
  • Getting the Example Working Locally
  • The File Structure Rationale
  • Changing Example Files

Quick Start

To create a Faust project using the Faust Getting Started Example, run in your terminal:

npx create-next-app \
    -e https://github.com/wpengine/faustjs/tree/canary \
    --example-path examples/next/faustwp-getting-started \
    --use-npmCode language: Shell Session (shell)

Now that the project was created, cd into your new app folder. For this tutorial, we use the folder name MyProject:

cd MyProject

Once inside your project folder root, copy the sample .env.local.sample file and create a new one called .env.local:

cp .env.local.sample .env.localCode language: CSS (css)

We will update the .env.local variables shortly. But for now, run the local development server:

npm run dev

Once the development environment is up and running, navigate to http://localhost:3000 in your browser to view it.

Currently, the posts and pages you see are coming from our WordPress site at https://faustexample.wpengine.com. In the next step, we’ll show you how to hook up your own WordPress site.

Connecting Your WordPress Site

As mentioned above, the Faust Getting Started Example project is being fed content from our WordPress demo site at https://faustexample.wpengine.com. While that’s cool and all, let’s get your WordPress site wired up.

Before you can change the WordPress site that the app pulls content from, we first need to install a few required plugins:

• Faust
• WPGraphQL

Once the required plugins have been installed and activated properly, open the .env.local file you created earlier. It should look something like this:

# Your WordPress site URL
NEXT_PUBLIC_WORDPRESS_URL=https://faustexample.wpengine.com

# Plugin secret found in WordPress Settings->Faust
# FAUST_SECRET_KEY=YOUR_PLUGIN_SECRETCode language: PHP (php)

Update the NEXT_PUBLIC_WORDPRESS_URL value with your WordPress site URL (be sure to include http:// or https://).

Additionally, update the FAUST_SECRET_KEY value with the Secret Key found in Settings → Faust in your WordPress admin area to support previews.

NOTE for users of Atlas and/or Local:
If deploying from the Atlas portal using your own repository without beginning with a blueprint, you will need to set your environment variables manually. Learn how by taking a look at our FAQs.

If using Local, ensure that in Local’s advanced settings, your router mode is set to Site Domains to match your NEXT_PUBLIC_WORDPRESS_URL value.

Set your Front-end Site URL

To ensure certain features of Faust function as expected, such as previews, be sure to set the Front-end Site URL in the Faust WordPress Plugin Settings. It is the URL to your headless front-end. This is used for authenticated post previews and for rewriting links to point to your front-end site.

1. Navigate to the Settings → Faust settings page.
2. Enter in the base url of your headless WordPress site, i.e. http://localhost:3000 (local development) or http://www.mysiteurl.com in the Front-end site URL setting.

Click Save Changes .

Check Your Permalinks

Finally, ensure your permalink structure in WP Admin -> Settings -> Permalinks is not set to “plain”:

NOTE:
Faust resolves templates similar to the Template Hierarchy in WordPress, but “plain” permalinks are not supported due to constraints in Next.js.

Start Editing

With your project created and development environment running successfully, you can now edit wp-templates/front-page.js and see the updated results in your browser. There is a lot more functionality and more exciting features in Faust but this gets you off and running!

Further Learning

After you get comfortable with creating and running a Faust project it’s time to take it up a notch and dig a little deeper.

Next Steps

• Example Project Walkthrough Structure – Continue learning about the project structure, how to change styles, layout, etc.
• Authentication – Add user auth to your headless site utilizing Faust and WordPress
• Setting Up Post and Page Previews – Learn the steps for viewing your WordPress content on the headless frontend as drafts or even before publishing.