Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions src/pages/docs/how-to/create-a-plugin/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
export const metadata = {
title: "Create A Plugin",
};

Faust plugins are a structured way to extend or alter the framework's behavior, very much like WordPress plugins do in a traditional WordPress environment. Instead of `PHP`, however, Faust's plugins are written in JavaScript/TypeScript, leveraging actions and filters to deliver similar flexibility in a headless architecture.

## Steps

### 1. Basic setup

If you haven't already, follow the [Basic Setup](/docs/how-to/basic-setup/) steps to get Faust.js set up.

### 2. Create A Plugins Folder and file

In its very basic form, a Faust Plugin is a JavaScript class with an `apply` method. This apply method has a parameter called `hooks`, which is passed from `@wordpress/hooks`. Create a folder in the root of your Faust project called `plugin`. In the folder, create a file called `SamplePlugin.js`. In this file, add this code block:

```js title="plugins/SamplePlugin.js"
import { FaustHooks } from "@faustwp/core";

export class MyPlugin {
/**
* @param {FaustHooks} hooks
*/
apply(hooks) {
// Plugin logic goes here
}
}
```

The `hooks` parameter is an object which contains the functions `addFilter` and `addAction`, amongst others. You can then use these functions to call the respective actions and filters to tap into Faust like so:

```js {10-16} title="plugins/SamplePlugin.js "
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.
},
);
}
}
```

> [!important] Please Note
> `experimentalPlugins` is being deprecated and replaced with `plugins` in the `faust.config.js` file.
> Please update your configuration accordingly.

### 3. Add The Plugin to the Faust Config

You can then implement the plugin by adding it to the plugins property in the App's `faust.config.js` file:

```js title="faust.config.js"
import { setConfig } from "@faustwp/core";
import templates from "./wp-templates";
import possibleTypes from "./possibleTypes.json";
import { MyPlugin } from "./plugins/MyPlugin.js";

/**
* @type {import('@faustwp/core').FaustConfig}
*/
export default setConfig({
templates,
plugins: [new MyPlugin()],
possibleTypes,
});
```
4 changes: 4 additions & 0 deletions src/pages/docs/nav.json
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@
{
"title": "Post Previews",
"route": "/docs/how-to/post-previews/"
},
{
"title": "Create A Plugin",
"route": "/docs/how-to/create-a-plugin/"
}
]
},
Expand Down
Loading