diff --git a/src/pages/docs/how-to/create-a-plugin/index.mdx b/src/pages/docs/how-to/create-a-plugin/index.mdx new file mode 100644 index 00000000..4b275e24 --- /dev/null +++ b/src/pages/docs/how-to/create-a-plugin/index.mdx @@ -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, +}); +``` diff --git a/src/pages/docs/nav.json b/src/pages/docs/nav.json index bd2f0435..9ee5aa9a 100644 --- a/src/pages/docs/nav.json +++ b/src/pages/docs/nav.json @@ -27,6 +27,10 @@ { "title": "Post Previews", "route": "/docs/how-to/post-previews/" + }, + { + "title": "Create A Plugin", + "route": "/docs/how-to/create-a-plugin/" } ] },