Faust.js

https://github.com/wpengine/faustjs
Admin
Faust.js is a toolkit for building Next.js applications for headless WordPress sites, simplifying...
Tokens:70,864
Snippets:207
Trust Score:9.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Run Project

Source: https://github.com/wpengine/faustjs/blob/canary/examples/next/block-support/README.md

Installs Node.js dependencies using npm, sets the Node.js version using nvm, and then runs the development server. This prepares and launches the Faust.js block editor example.

```bash
nvm use
npm install
npm run blockset
npm run dev
```

--------------------------------

### Install Frontend Dependencies and Start Development Server

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

Commands to install NPM packages for the Next.js frontend and start the development server. It also includes generating necessary GraphQL type definitions.

```sh
npm install
npm run generate
npm run dev
```

--------------------------------

### NPM Package Setup

Source: https://github.com/wpengine/faustjs/blob/canary/packages/faustwp-core/DEVELOPMENT.md

Commands to install project dependencies and start the development server using NPM workspaces.

```bash
npm install
npm run dev
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/wpengine/faustjs/blob/canary/examples/next/block-support/README.md

Clones the Faust.js repository and navigates into the block-support example directory. This is the initial step to get the project files.

```bash
git clone git@github.com:wpengine/faustjs.git my-project
cd my-project/examples/next/block-support/
```

--------------------------------

### Install Faust.js Dependencies

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Installs the essential NPM packages required for integrating Faust.js with a Next.js application, including core libraries and the command-line interface.

```bash
npm install @apollo/client @faustwp/core graphql @faustwp/cli
```

--------------------------------

### WordPress Setup and Testing Commands

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Commands for setting up a WordPress test environment using Docker, installing WPGraphQL, exporting a database dump, and running acceptance tests with Codeception.

```bash
cd plugins/faustwp
composer install
docker-compose up -d --build
docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root
docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp core update-db --allow-root
docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp db export tests/_data/dump.sql --allow-root
vendor/bin/codecept run acceptance
```

--------------------------------

### End-to-End Testing Environment Setup

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Steps to set up the environment for end-to-end testing, including installing Docker, Composer, Chrome, and Chromedriver.

```sh
# Install Docker
# Install Composer
# Install Google Chrome
# Install Chromedriver
# Unzip chromedriver and move to /usr/local/bin
mv chromedriver /usr/local/bin
# Verify chromedriver installation
chromedriver --version
```

--------------------------------

### Start Faust.js Core Development Server

Source: https://github.com/wpengine/faustjs/blob/canary/packages/faustwp-core/LOCAL_DEVELOPMENT.md

Installs dependencies, builds, and starts the development server for the `@faustwp/core` package itself. This should be run from the Faust repo directory.

```shell
npm install --workspace=@faustwp/core
npm run build --workspace=@faustwp/core
npm run dev --workspace=@faustwp/core
```

--------------------------------

### Configure npm Scripts for Faust.js Deployment (JSON)

Source: https://github.com/wpengine/faustjs/blob/canary/docs/explanation/deploy-your-app/index.md

This snippet shows how to configure the `scripts` section in your `package.json` file for building and starting a Faust.js application. It defines `build` and `start` commands using `faust build` and `faust start` respectively, essential for self-hosting.

```json
{
	"scripts": {
		"build": "faust build",
		"start": "faust start"
	}
}
```

--------------------------------

### Start Project Site Development Server

Source: https://github.com/wpengine/faustjs/blob/canary/packages/faustwp-core/LOCAL_DEVELOPMENT.md

Installs project dependencies and starts the development server for the user's Faust.js project site. This should be run from the project site directory.

```shell
yarn install
yarn dev
```

--------------------------------

### FaustWP Plugin WordPress Unit Tests

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Commands to start Docker containers, initialize the testing environment, install WP GraphQL, and run unit tests for the FaustWP plugin.

```sh
composer run docker:start
WP_VERSION=6.4.2 composer run docker:start
docker-compose exec -e COVERAGE=1 wordpress init-testing-environment.sh
docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) wp plugin install wp-graphql --activate --allow-root
docker exec --workdir=/var/www/html/wp-content/plugins/faustwp $(docker-compose ps -q wordpress) composer test
composer run docker:stop
```

--------------------------------

### Install Faust.js and Apollo Dependencies

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/migrate-from-legacy-faust/index.md

Installs the necessary Faust.js CLI, core packages, GraphQL, and Apollo Client dependencies using npm. This is the first step in setting up the new project structure.

```bash
npm i @faustwp/cli @faustwp/core graphql @apollo/client
```

--------------------------------

### Install next-secure-headers Package

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/post-previews/index.md

Installs the `next-secure-headers` package via npm, which is required for adding security headers to the Next.js application. This is a prerequisite for configuring `next.config.js`.

```bash
npm install next-secure-headers
```

--------------------------------

### Install @faustwp/blocks Package

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/rendering-blocks/index.md

Installs the necessary `@faustwp/blocks` package using npm. This package provides core block components for use with Faust.js.

```bash
npm install @faustwp/blocks
```

--------------------------------

### Clone Faust.js Block-Support Example App

Source: https://github.com/wpengine/faustjs/blob/canary/docs/reference/blockset/index.md

Command to clone and set up a Faust.js example application that includes block support. This demonstrates the integration and usage of the `blockset` command in a practical context.

```bash
npx create-next-app \
-e https://github.com/wpengine/faustjs/tree/canary \
--example-path examples/next/block-support \
--use-npm
```

--------------------------------

### Faust.js API Route Setup

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Creates a dynamic API route within the Next.js application to handle Faust.js requests, ensuring the core API router is correctly imported and configured.

```js
import "../../faust.config"; // Adjust path as necessary

export { apiRouter as default } from "@faustwp/core";
```

--------------------------------

### .env.local Configuration

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Sets up environment variables for a Next.js project, specifying the WordPress site URL and the Faust plugin's secret key for authentication and data fetching.

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

# Plugin secret found in WordPress Settings->Faust
FAUST_SECRET_KEY=YOUR_PLUGIN_SECRET
```

--------------------------------

### Install highlight.js Package

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/custom-blocks/index.md

This bash command installs the highlight.js library, which is used for syntax highlighting in the frontend application. It adds the package to your project's dependencies.

```bash
npm add highlight.js
```

--------------------------------

### Next.js App Wrapper

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Updates the main Next.js application file (`_app.js`) to wrap the component tree with `FaustProvider`, enabling Faust.js functionality across the application and managing routing.

```js
import { useRouter } from "next/router";
import { FaustProvider } from "@faustwp/core";
import "../../faust.config";

export default function App({ Component, pageProps }) {
	const router = useRouter();

	return (
		<FaustProvider pageProps={pageProps}>
			<Component {...pageProps} key={router.asPath} />
		</FaustProvider>
	);
}
```

--------------------------------

### Faust.js Configuration

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Defines the main configuration for the Faust.js core, linking custom WordPress templates, specifying plugins, and including GraphQL possible types for schema introspection.

```js
import { setConfig } from "@faustwp/core";
import templates from "./src/wp-templates";
import possibleTypes from "./possibleTypes.json";

/**
 * @type {import('@faustwp/core').FaustConfig}
 **/
export default setConfig({
	templates,
	plugins: [],
	possibleTypes,
});
```

--------------------------------

### Example Rendered Paragraph Block HTML

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

An example of the HTML output for a paragraph block after Faust.js has processed it, including custom styles and classes applied in the WordPress editor.

```html
<div class="paragraph-block-wrapper">
	<p
		class="is-style-text-annotation has-large-font-size is-style-text-annotation--1"
		id="anchors-away"
		style="
      border-width: 4px;
      padding-top: var(--wp--preset--spacing--20);
      padding-right: var(--wp--preset--spacing--40);
      padding-bottom: var(--wp--preset--spacing--20);
      padding-left: var(--wp--preset--spacing--40);
    ">
		Welcome to WordPress. This is your first post. Edit or delete it, then start
		writing!
	</p>
</div>
```

--------------------------------

### Configure Faust.js Frontend Environment Variables

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

Example of the .env.local file for a Faust.js Next.js application. It includes the WordPress URL and the Faust.js secret key for authenticated requests.

```env
# Your WordPress site URL
NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8881

# Plugin secret found in WordPress Settings->Faust
FAUST_SECRET_KEY=ABC123

```

--------------------------------

### Environment Configuration

Source: https://github.com/wpengine/faustjs/blob/canary/packages/faustwp-core/DEVELOPMENT.md

Example of the `.env.local` file required in the `packages/faustwp-core` directory to configure the GraphQL endpoint.

```dotenv
# GraphQL Endpoint
NEXT_PUBLIC_WORDPRESS_URL=http://headless.local
```

--------------------------------

### End-to-End Testing Front-end Setup

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Configuration for end-to-end tests, including creating a .env.test file with WordPress URL and Faust secret key, and running the development server.

```sh
# Create .env.test file in examples/next/getting-started
# .env.test content:
# NEXT_PUBLIC_WORDPRESS_URL=http://localhost:8080
# FAUST_SECRET_KEY=00000000-0000-4000-8000-00000000000000000001

# Run dev server with test environment
NODE_ENV=test npm run dev
```

--------------------------------

### package.json Scripts for Type Generation

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Adds a custom script to the `package.json` file to execute the Faust CLI command for generating GraphQL possible types, which is crucial for schema introspection.

```json
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "generate": "faust generatePossibleTypes",
    "start": "next start",
    "lint": "next lint"
  },
```

--------------------------------

### Create Environment File

Source: https://github.com/wpengine/faustjs/blob/canary/examples/next/block-support/README.md

Creates an empty .env.local file to store local environment variables. This file is crucial for configuring the application's connection to your WordPress instance.

```bash
touch .env.local
```

--------------------------------

### Environment Variables Configuration

Source: https://github.com/wpengine/faustjs/blob/canary/examples/next/block-support/README.md

Configures the .env.local file with necessary WordPress and site URLs. These variables are used by Faust.js for connecting to the headless CMS and for sitemap generation.

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

# Plugin secret found in WordPress Settings->Headless
#FAUST_SECRET_KEY=

# The URL of your site, used by Faust for sitemap generation, however you can name this whatever you want.
NEXT_PUBLIC_SITE_URL=http://localhost:3000
```

--------------------------------

### Clone Faust.js Next.js Tutorial Project

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

Command to download the starter Next.js project for the Faust.js tutorial using degit. This sets up the project structure and initial files required for the tutorial.

```sh
npx degit wpengine/faustjs/examples/next/tutorial faust-tutorial
```

--------------------------------

### Set Up Local WordPress Backend with Faust.js

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

Command to initialize a local WordPress environment using the wp-now NPM package and a provided blueprint file. It installs necessary plugins like FaustWP and WPGraphQL.

```sh
npm run wp-dev
```

--------------------------------

### Install GraphQL Codegen CLI

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/generate-types-with-graphql-codegen/index.md

Installs the necessary development dependencies, including TypeScript and the GraphQL Code Generator CLI, to your project.

```bash
npm install -D typescript @graphql-codegen/cli
```

--------------------------------

### Logout Button Usage Example

Source: https://github.com/wpengine/faustjs/blob/canary/docs/reference/use-logout/index.md

An example demonstrating how to integrate the useLogout hook into a React component to display a logout button and handle redirection upon successful logout.

```JavaScript
import { useLogout } from "@faustwp/core";

export function AuthenticatedView() {
	const { logout } = useLogout();

	return (
		<>
			<button onClick={() => logout("/")}>Logout</button>
		</>
	);
}
```

--------------------------------

### Faust.js Single Post Template Component

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Defines a React component for rendering single blog posts in Faust.js. It fetches post title and content using GraphQL and includes static query and variable definitions for dynamic content retrieval.

```js
import { gql } from "@apollo/client";

export default function SingleTemplate(props) {
	const { title, content } = props.data.post;

	return (
		<>
			<h1>{title}</h1>
			<div dangerouslySetInnerHTML={{ __html: content }} />
		</>
	);
}

SingleTemplate.query = gql`
	query GetPost($uri: ID!) {
		post(id: $uri, idType: URI) {
			title
			content
		}
	}
`;

SingleTemplate.variables = (seedQuery, ctx) => {
	return {
		uri: seedQuery?.uri,
	};
};
```

--------------------------------

### Install @faustwp/blocks and Dependencies

Source: https://github.com/wpengine/faustjs/blob/canary/packages/blocks/README.md

Installs the @faustwp/blocks package and its peer dependency @wordpress/style-engine using npm. These are essential for integrating Gutenberg blocks into your Faust.js project.

```bash
npm i @faustwp/blocks
npm i @wordpress/style-engine
```

--------------------------------

### Faust.js Catch-all Route for WordPress Content

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/basic-setup/index.md

Sets up a catch-all route in Next.js to handle dynamic WordPress content. It uses `WordPressTemplate` from `@faustwp/core` to render content based on Faust.js templates and defines static generation properties for optimal performance.

```js
import { getWordPressProps, WordPressTemplate } from "@faustwp/core";

export default function Page(props) {
	return <WordPressTemplate {...props} />;
}

export function getStaticProps(ctx) {
	return getWordPressProps({ ctx });
}

export async function getStaticPaths() {
	return {
		paths: [],
		fallback: "blocking",
	};
}
```

--------------------------------

### Faust Plugin with Filter Example

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/create-a-plugin/index.md

Demonstrates using the `addFilter` hook within a Faust.js plugin to modify framework behavior. This example targets the `possibleTemplatesList` hook to customize template resolution.

```javascript
import { FaustHooks } from "@faustwp/core";

export class MyPlugin {
	/**
	 * @param {FaustHooks} hooks
	 */
	apply(hooks) {
		const { addAction, addFilter } = hooks;

		addFilter(
			"possibleTemplatesList",
			"my-namespace",
			(possibleTemplates, context) => {
				// Filter logic goes here.
			},
		);
	}
}
```

--------------------------------

### Install Block Editor Utilities Dependencies

Source: https://github.com/wpengine/faustjs/blob/canary/packages/block-editor-utils/README.md

Installs the necessary development dependencies, including `@wordpress/scripts` and `@faustwp/block-editor-utils`, using npm. These are essential for building and managing Gutenberg blocks.

```bash
$ npm install @wordpress/scripts @faustwp/block-editor-utils --save-dev
```

--------------------------------

### Monorepo Navigation and Build Scripts

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Instructions for navigating the Faust.js monorepo and executing build/deploy scripts using npm.

```bash
# Navigate to a specific project directory within the monorepo
cd packages/faustwp-core

# Run project-specific build or test scripts
npm run build
npm run test

# Run a top-level build script for the entire monorepo (if available)
npm run build
```

--------------------------------

### Example GraphQL Response for CoreCode Block

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/custom-blocks/index.md

An example JSON response from a GraphQL query showing the `renderedHtml` and attributes for a `CoreCode` block. This illustrates the data structure received by the frontend for rendering.

```json
{
	"data": {
		"post": {
			"editorBlocks": [
				{
					"renderedHtml": "\n<pre class=\"wp-block-code has-border-color has-tertiary-background-color has-text-color has-background has-small-font-size\" style=\"border-color:#333333;border-width:2px;color:#333333\"><code>// Computes the nth Fibonacci number\nfunction fib(n) {\n    var a = 0, b = 1, c;\n    if (n < 3) {\n        if (n < 0) return fib(-n);\n        if (n === 0) return 0;\n        return 1;\n    }\n    while (--n)\n        c = a + b, a = b, b = c;\n    return c;\n}</code></pre>\n",
					"attributes": {
						"borderColor": null,
						"backgroundColor": "tertiary",
						"content": "// Computes the nth Fibonacci number\nfunction fib(n) {\n    var a = 0, b = 1, c;\n    if (n < 3) {\n        if (n < 0) return fib(-n);\n        if (n === 0) return 0;\n        return 1;\n    }\n    while (--n)\n        c = a + b, a = b, b = c;\n    return c;\n}",
						"style": "{\"color\":{\"text\":\"#333333\"},\"border\":{\"color\":\"#333333\",\"width\":\"2px\"}}",
						"textColor": null,
						"fontSize": "small"
					}
				}
			]
		}
	}
}
```

--------------------------------

### Complete Single Template for Post Previews

Source: https://github.com/wpengine/faustjs/blob/canary/docs/tutorial/learn-faust/index.md

The full `single.js` template file in Faust.js, demonstrating how to integrate loading states, pass preview context via variables, and use a GraphQL query that supports fetching draft posts. It renders the post title and content.

```jsx
import { gql } from '@apollo/client';

export default function SingleTemplate(props) {
	const { title, content } = props.data.post;

	if (props.loading) {
		return <p>Loading...</p>;
	}

	return (
		<>
			<h1>{title}</h1>
			<div dangerouslySetInnerHTML={{ __html: content }} />
		</>
	);
}

SingleTemplate.query = gql`
	query GetPost($uri: ID!, $asPreview: Boolean = false) {
		post(id: $uri, idType: URI, asPreview: $asPreview) {
			title
			content
		}
	}
`;

SingleTemplate.variables = (seedQuery, ctx) => {
	return {
		uri: seedQuery?.uri,
		asPreview: ctx?.asPreview,
	};
};
```

--------------------------------

### FaustWP Plugin Symlinking

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Instructions to symlink the FaustWP plugin from the monorepo into a WordPress installation's plugin directory.

```sh
ln -s /path/to/faustjs/plugins/faustwp /path/to/wordpress/wp-content/plugins/faustwp
```

--------------------------------

### Create Basic React Page for Client-Side Fetching

Source: https://github.com/wpengine/faustjs/blob/canary/docs/how-to/query-data-in-the-browser/index.md

Demonstrates creating a simple React component to serve as a client-side page. This serves as the initial structure before integrating data fetching logic.

```javascript
export default function Page(props) {
	return <h1>Client Page</h1>;
}
```

--------------------------------

### Check Yarn Version

Source: https://github.com/wpengine/faustjs/blob/canary/packages/faustwp-core/LOCAL_DEVELOPMENT.md

Verifies the currently installed version of Yarn. This is a prerequisite step to ensure compatibility for linking local packages.

```shell
yarn --version
```

--------------------------------

### Passing Extra Arguments Example

Source: https://github.com/wpengine/faustjs/blob/canary/docs/reference/get-wordpress-props/index.md

Illustrates how to pass custom data to the `extra` property within the `getWordPressProps` configuration object in data fetching functions.

```js
export function getStaticProps(ctx) {
	return getWordPressProps({ ctx, extra: { hello: "world" } });
}
```

--------------------------------

### NPM Package Management

Source: https://github.com/wpengine/faustjs/blob/canary/DEVELOPMENT.md

Commands to install dependencies, run the development server, and clean the project for Faust.js NPM packages managed via Workspaces.

```sh
npm install
npm run dev
npm run clean
```
Tokens:
Raw