This guide covers how to set up Faust plugins and how to use them in your site.

Prerequisites:

• Faust Plugin is installed on your WordPress Site.
• You have created a Faust headless project.

Experimental Config Object

NOTE:
experimentalPlugins is being deprecated and replaced with plugins in the faust.config.js file. Please update your configuration accordingly.

The config object is used to set up plugins via the plugins property. It’s a property that takes an array of plugin class instances. You or the end user can then implement the plugin by adding it to the plugins property in the App’s faust.config.js file. See the example below:

// faust.config.js
import { setConfig } from '@faustwp/core';
import templates from './wp-templates';
import possibleTypes from './possibleTypes.json';
import { MyPlugin } from './MyPlugin.js';

/**
 * @type {import('@faustwp/core').FaustConfig}
 **/
export default setConfig({
  templates,
  plugins: [new MyPlugin()],
  possibleTypes,
});
Code language: JavaScript (javascript)

Plugin Options

NOTE
The Faust plugins utilize the @wordpress/hooks library found here.

When you create a plugin you will use the @wordpress/hooks library as well as Faust filters.

Create a plugin

To get started, follow our guide on Creating a plugin.

Example Usage

Tapping into Apollo

The ApolloClient class contains Apollo’s core client-side API. It backs all available view-layer integrations. Learn more about ApolloClient options here.

Below is an example using addFilter that modifies the ApolloClientOptions.

import {
  ApolloClientOptions,
  NormalizedCacheObject,
} from '@apollo/client';

addFilter(
    hookName: 'apolloClientOptions',
    namespace: string,
    callback: (
      apolloClientOptions: ApolloClientOptions<NormalizedCacheObject>,
      context: Record<string, never>,
    ) => ApolloClientOptions<NormalizedCacheObject>,
    priority?: number | undefined,
  ): void;
Code language: JavaScript (javascript)

InMemoryCache is the cache used by almost every instance of ApolloClient. Read more about InMemoryCache here.

Below is an example using addFilter that modifies the InMemoryCache.

import {
  InMemoryCacheConfig,
} from '@apollo/client';

addFilter(
    hookName: 'apolloClientInMemoryCacheOptions',
    namespace: string,
    callback: (
      inMemoryCacheObject: InMemoryCacheConfig,
      context: Record<string, never>,
    ) => InMemoryCacheConfig,
    priority?: number | undefined,
  ): void;
Code language: JavaScript (javascript)

Persisted Queries

Here we show an example of a persisted query using a Faust plugin. You can find this example on GitHub here.

It uses the addFilter inside a Faust plugin called PersistedQueriesPlugin. It filters apolloClientOptions and pulls the link as existingLink. If the existingLink is an instance of HttpLink, it adds the existingLink to the persistedQueriesLink. If it’s not an instance of HttpLink, it adds the httpLink to the persistedQueriesLink.

// PersistedQueriesPlugin.js
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { HttpLink } from '@apollo/client';
import { sha256 } from 'crypto-hash';
import { getGraphqlEndpoint } from '@faustwp/core/dist/mjs/lib/getGraphqlEndpoint';

const httpLink = new HttpLink({ uri: getGraphqlEndpoint() });
const persistedQueriesLink = createPersistedQueryLink({
  sha256,
  useGETForHashedQueries: true,
});

class PersistedQueriesPlugin {
  apply({ addFilter }) {
    addFilter('apolloClientOptions', 'faust', (apolloClientOptions) => {
      const existingLink = apolloClientOptions?.link;
      return {
        ...apolloClientOptions,
        link:
          existingLink instanceof HttpLink
            ? persistedQueriesLink.concat(existingLink)
            : persistedQueriesLink.concat(httpLink),
      };
    });
  }
}

export default PersistedQueriesPlugin;
Code language: JavaScript (javascript)

Additional Filters

For further learning about Faust filters, check out the Faust Filters, here.