--- title: Advanced Plugin API label: Advanced Plugin API order: 25 desc: Use definePlugin and RegisteredPlugins to build powerful, interoperable plugins with execution ordering and typed cross-plugin communication. keywords: plugins, definePlugin, RegisteredPlugins, order, cross-plugin, configuration, extensions, typescript, documentation, Content Management System, cms, headless, javascript, node, react, nextjs --- Payload's plugin system is built around a simple contract: a plugin is a function that receives a config and returns a modified config. That simplicity is intentional and permanent — the basics will never change. This page covers the advanced plugin API that makes plugins more powerful: execution ordering via `order`, typed cross-plugin communication via `RegisteredPlugins`, and the `definePlugin` helper that ties it all together. The API on this page is **experimental**. It is safe to use across Payload's own plugins, but the surface may change before being declared stable. ## The basics still work The plain function form is unchanged and will always be supported: ```ts import type { Config } from 'payload' export const myPlugin = (opts: MyOptions) => (config: Config): Config => ({ ...config, collections: [...(config.collections || []), myCollection], }) ``` Everything below builds on top of this — none of it is required for simple plugins. ## `definePlugin` — recommended for published plugins `definePlugin` replaces the boilerplate of manually attaching `slug`, `order`, and `options` to the function after the fact. Your plugin function receives a single object containing `config`, a `plugins` map, and the user-provided `options`: ```ts export const seoPlugin = definePlugin({ slug: 'plugin-seo', order: 10, plugin: ({ config, options }) => ({ ...config, collections: [ ...(config.collections || []), seoCollection(options.collections), ], }), }) ``` To make options optional (callable with no arguments), include `undefined` in the type parameter: ```ts export const analyticsPlugin = definePlugin({ slug: 'plugin-analytics', plugin: ({ config, options }) => ({ ...config }), // options: AnalyticsOptions | undefined }) analyticsPlugin() // ✅ no arguments required ``` Import it from `payload`: ```ts import { definePlugin } from 'payload' ``` The result of `definePlugin` is a factory function — call it with your options to get a `Plugin`: ```ts // payload.config.ts plugins: [seoPlugin({ collections: ['pages', 'posts'] })] ``` ## Execution ordering with `order` By default, plugins execute in the order they appear in the `plugins` array. Setting `order` lets you declare execution order explicitly, regardless of array position. **Lower order values run first.** The default is `0`. ```ts // This plugin runs first (order 1), even though it's listed second plugins: [ analyticsPlugin({ trackingId: 'UA-...' }), // order 10 — runs second basePlugin(), // order 1 — runs first ] ``` ### Suggested order conventions Settle on a convention so the ecosystem converges: | Range | Use case | | -------- | ------------------------------------------------------------- | | Negative | Must run before everything — config normalization, polyfills | | `0` | Default — no dependencies on other plugins | | `10–50` | Depends on collections or fields added by other plugins | | `100+` | Must run last — audit, introspection, or final-config plugins | ## Cross-plugin communication Plugins often need to be aware of each other. The pattern for this is: 1. A plugin with a `slug` exposes its `options` on the plugin function 2. Another plugin finds it via the `plugins` map and mutates or replaces those options before the first plugin runs 3. When the first plugin executes, it reads its current `options`, so it sees the changes Since a plugin reads its `options` when it runs, changes made by plugins with a lower `order` are picked up without re-execution. ### The `plugins` map Every plugin created with `definePlugin` receives a `plugins` map — a slug-keyed object of all plugins in the config. No imports needed: ```ts export const writerPlugin = definePlugin({ slug: 'my-writer', order: 1, plugin: ({ config, plugins }) => { const seo = plugins['plugin-seo'] if (seo) { seo.options = { ...seo.options, collections: [...(seo.options?.collections ?? []), 'my-collection'], } } return config }, }) ``` For registered slugs (see below), the `plugins` map entries are automatically typed — no cast needed. ### `RegisteredPlugins` — module augmentation for type safety Plugin packages can register their slug and options type by augmenting the `RegisteredPlugins` interface. This ships with the package and is activated automatically when the plugin is imported — no code generation required. ```ts // packages/plugin-seo/src/index.ts export type SEOPluginOptions = { collections: string[] generateTitle?: (doc: Record) => string } export const seoPlugin = definePlugin({ slug: 'plugin-seo', order: 10, plugin: ({ config, options }) => ({ ...config, // extend config here using options }), }) // Augment RegisteredPlugins — activated at import time, no generation step declare module 'payload' { interface RegisteredPlugins { 'plugin-seo': SEOPluginOptions } } ``` Once a plugin package augments `RegisteredPlugins`, any project that imports it gets typed access via the `plugins` map: ```ts export const writerPlugin = definePlugin({ slug: 'my-writer', order: 1, plugin: ({ config, plugins }) => { // plugins['plugin-seo'] is typed — options is SEOPluginOptions const seo = plugins['plugin-seo'] if (seo) { seo.options = { ...seo.options, collections: [...(seo.options?.collections ?? []), 'my-collection'], } } return config }, }) ``` ## Full example: two interoperating plugins Here is a complete example of two decoupled plugins that communicate via the `plugins` map. The writer plugin (order 1) runs first and injects an item into the reader plugin's options. The reader plugin (order 10) runs second and sees the injected item. ```ts import type { Config } from 'payload' import { definePlugin } from 'payload' // --- reader plugin --- export type ReaderPluginOptions = { items: Array<{ name: string }> } export const readerPlugin = definePlugin({ slug: 'my-reader', order: 10, plugin: ({ config, options }) => ({ ...config, custom: { ...config.custom, items: options.items.map((i) => i.name), }, }), }) declare module 'payload' { interface RegisteredPlugins { 'my-reader': ReaderPluginOptions } } // --- writer plugin (separate package) --- export const writerPlugin = definePlugin({ slug: 'my-writer', order: 1, plugin: ({ config, plugins }) => { // Runs before reader — replaces reader's options before reader executes const reader = plugins['my-reader'] if (reader) { reader.options = { ...reader.options, items: [ ...(reader.options?.items ?? []), { name: 'injected-by-writer' }, ], } } return config }, }) // --- payload.config.ts --- plugins: [readerPlugin({ items: [{ name: 'user-provided' }] }), writerPlugin()] // Result: reader sees ['user-provided', 'injected-by-writer'] ``` ## When to use cross-plugin mutation vs. direct options Use cross-plugin mutation (`plugins` map + options mutation) when: - The two plugins are **decoupled packages** — one doesn't import the other - The extending plugin is **optional** — the target plugin should work without it - You want users to install both plugins independently without wiring them together manually Use direct options when: - The relationship is **intentional and documented** — the user is expected to pass options directly - The plugins are in the **same package** and share types already ## Checking if a plugin is installed You can check whether a plugin is present without importing it: ```ts const hasSeo = config.plugins?.some((p) => p.slug === 'plugin-seo') ?? false ``` Or via the `plugins` map inside a `definePlugin` function: ```ts plugin: ({ config, plugins }) => { if (plugins['plugin-seo']) { // plugin-seo is installed — safe to mutate its options } return config } ```