Merge pull request #243 from wpengine/reference/faust-plugin-filters

Reference: faust plugin system filters

Author: moonmeister

src/pages/docs/nav.json

@@ -57,6 +57,10 @@
 		"title": "Reference",
 		"route": "/docs/reference/",
 		"children": [
+			{
+				"title": "Faust Plugin System Filters",
+				"route": "/docs/reference/faust-plugin-system-filters"
+			},
 			{
 				"title": "fromThemeJson",
 				"route": "/docs/reference/from-theme-json"

src/pages/docs/reference/faust-plugin-system-filters/index.mdx

@@ -0,0 +1,205 @@
+export const metadata = {
+	title: "Faust Plugin System Filters",
+	description: "API information for Faust's plugin system.",
+};
+
+Below are the different types of filters available to you in the Faust Plugin System. Each filter callback contains two parameters, the first parameter is the filtered data. For instance the first parameter in the `possibleTemplatesList` filter is `possibleTemplates`, a string array of templates. The second parameter of every filter is a `context` object. This object may contain information needed to make modifications to the filtered data.
+
+> [!INFO]
+> Check out this comprehensive guide to creating and including Faust plugins in your project: [Create a Plugin](/docs/how-to/create-a-plugin).
+
+## `apolloClientInMemoryCacheOptions`
+
+This allows you to modify the [Apollo Client’s `InMemoryCache` config](https://www.apollographql.com/docs/react/api/cache/InMemoryCache).
+
+```ts title="faustFilters.config.ts"
+import {
+  InMemoryCacheConfig,
+} from '@apollo/client';
+
+addFilter(
+    hookName: 'apolloClientInMemoryCacheOptions',
+    namespace: string,
+    callback: (
+      inMemoryCacheObject: InMemoryCacheConfig,
+      context: Record<string, never>,
+    ) => InMemoryCacheConfig,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `apolloClientOptions`
+
+Allows you to modify the [Apollo Client’s options](https://www.apollographql.com/docs/react/api/core/ApolloClient).
+
+```ts title="faustFilters.config.ts"
+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;
+```
+
+And here is an example:
+
+```js title="plugins/persisted-queries-plugin.js"
+class PersistedQueriesPlugin {
+	apply({ addFilter }) {
+		addFilter("apolloClientOptions", "faust", (apolloClientOptions) => {
+			const existingLink = apolloClientOptions?.link;
+			return {
+				...apolloClientOptions,
+				link:
+					existingLink instanceof HttpLink
+						? persistedQueriesLink.concat(existingLink)
+						: persistedQueriesLink.concat(httpLink),
+			};
+		});
+	}
+}
+```
+
+## `possibleTemplatesList`
+
+Allows you to modify the templates that are returned for a given URI.
+
+**Context Object**
+
+- `seedNode: SeedNode`: The seed node requested from the seed query
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'possibleTemplatesList',
+    namespace: string,
+    callback: (
+      possibleTemplates: string[],
+      context: { seedNode: SeedNode },
+    ) => string[],
+    priority?: number | undefined,
+  ): void;
+```
+
+## `seedQueryDocumentNode`
+
+Allows you to override the Seed Query.
+
+**Context Object**
+
+- `resolvedUrl: string`: The resolved URL for the given route.
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'seedQueryDocumentNode',
+    namespace: string,
+    callback: (
+      seedQuery: DocumentNode,
+      context: { resolvedUrl: string },
+    ) => DocumentNode,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `graphqlEndpoint`
+
+Allows you to override the GraphQL Endpoint.
+
+**Context Object**
+
+- `wpUrl: string`: The URL to the WordPress site
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'graphqlEndpoint',
+    namespace: string,
+    callback: (graphqlEndpoint: string, context: { wpUrl: string }) => string,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `wpHostname`
+
+Allows you to override the WordPress site URLs `hostname`.
+
+**Context Object**
+
+- `wpUrl: string`: The URL to the WordPress site
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'wpHostname',
+    namespace: string,
+    callback: (wpHostname: string, context: { wpUrl: string }) => string,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `wpUrl`
+
+Allows you to override the WordPress site URL.
+
+**Context Object**
+
+- `wpUrl: string`: The URL to the WordPress site
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'wpUrl',
+    namespace: string,
+    callback: (wpUrl: string, context: Record<string, never>) => string,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `toolbarNodes`
+
+> [!Important]
+> This filter is part of an experimental feature that has been deprecated. This feature will continue to function as-is, but will no longer revive bug fixes or other improvements. You may opt-in to using this feature by setting `experimentalToolbar: true` within your project’s `faust.config.js`.
+
+Allows you to modify Faust’s Toolbar nodes.
+
+**Context Object**
+
+- `seedNode: SeedNode`: The seed node requested from the seed query
+
+```ts title="faustFilters.config.ts"
+addFilter(
+    hookName: 'toolbarNodes',
+    namespace: string,
+    callback: (
+      toolbarNodes: FaustToolbarNodes,
+      context: { seedNode: SeedNode },
+    ) => FaustToolbarNodes,
+    priority?: number | undefined,
+  ): void;
+```
+
+## `resolvedUrl`
+
+Allows you to override the resolved URL in the Faust template system.
+
+**Context Object**
+
+- `nextContext: GetServerSidePropsContext | GetStaticPropsContext: The Next.js context object from either getServerSidePropsorgetStaticProps`.
+
+```ts title="faustFilters.config.ts"
+addFilter(
+  hookName: 'resolvedUrl',
+  namespace: string,
+  callback: (
+    resolvedUrl: string | null,
+    context: {
+      nextContext: GetServerSidePropsContext | GetStaticPropsContext;
+    },
+  ) => string | null,
+  priority?: number | undefined,
+): void;
+```