Payload is now part of Figma! Learn More
Simplify your stack and build anything. Or everything.
Schedule a Demo
USE CASES
Headless CMSEnterprise App BuilderHeadless E-CommerceDigital Asset Management
FEATURES
Multi-TenancyWhite LabelLocalizationAccess ControlAuth
CASE STUDIES

See what others are building with Payload.

Browse Case Studies
Build tomorrow’s web with a modern solution you truly own.
PAYLOAD IS FOR
DevelopersMarketing teamsEnterprise companiesAgencies & Consultancies
COMPARE PAYLOAD
Payload vs WordPressPayload vs ContentfulPayload vs SanityPayload vs StrapiPayload vs Directus
AGENCY TESTIMONIAL

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Become a PartnerFind a Partner
Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubReleasesBlogGuides & Tutorials
Community
RoadmapDiscordCommunity Help
Resources for Developers

Get the resources you need to start building today

Guides & TutorialsExplore Docs
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOAI Auto-EmbeddingPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftASICSBlue OriginHello BelloTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case studyBrowse all
LoginGet Started

Advanced Plugin API

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 basics still work

The plain function form is unchanged and will always be supported:

1
import type { Config } from 'payload'
2
3
export const myPlugin =
4
(opts: MyOptions) =>
5
(config: Config): Config => ({
6
...config,
7
collections: [...(config.collections || []), myCollection],
8
})

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 any user-provided options spread directly in:

1
export const seoPlugin = definePlugin<SEOPluginOptions>({
2
slug: 'plugin-seo',
3
order: 10,
4
plugin: ({ config, plugins, collections }) => ({
5
...config,
6
collections: [...(config.collections || []), seoCollection],
7
}),
8
})

Import it from payload:

1
import { definePlugin } from 'payload'

The result of definePlugin is a factory function — call it with your options to get a Plugin:

1
// payload.config.ts
2
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.

1
// This plugin runs first (order 1), even though it's listed second
2
plugins: [
3
analyticsPlugin({ trackingId: 'UA-...' }), // order 10 — runs second
4
basePlugin(), // order 1 — runs first
5
]

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 object — the same object passed at call time
  2. Another plugin finds it via the plugins map and mutates those options before the first plugin runs
  3. When the first plugin executes, it sees the mutated options

Since options are resolved before any plugin runs, this works cleanly 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:

1
export const writerPlugin = definePlugin({
2
slug: 'my-writer',
3
order: 1,
4
plugin: ({ config, plugins }) => {
5
const seo = plugins['plugin-seo']
6
seo?.options?.collections.push('my-collection')
7
return config
8
},
9
})

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.

1
// packages/plugin-seo/src/index.ts
2
export type SEOPluginOptions = {
3
collections: string[]
4
generateTitle?: (doc: Record<string, unknown>) => string
5
}
6
7
export const seoPlugin = definePlugin<SEOPluginOptions>({
8
slug: 'plugin-seo',
9
order: 10,
10
plugin: ({ config, collections }) => ({
11
...config,
12
// extend config here
13
}),
14
})
15
16
// Augment RegisteredPlugins — activated at import time, no generation step
17
declare module 'payload' {
18
interface RegisteredPlugins {
19
'plugin-seo': SEOPluginOptions
20
}
21
}

Once a plugin package augments RegisteredPlugins, any project that imports it gets typed access via the plugins map:

1
export const writerPlugin = definePlugin({
2
slug: 'my-writer',
3
order: 1,
4
plugin: ({ config, plugins }) => {
5
// plugins['plugin-seo'] is typed — options is SEOPluginOptions
6
plugins['plugin-seo']?.options?.collections.push('my-collection')
7
return config
8
},
9
})

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.

1
import type { Config } from 'payload'
2
import { definePlugin } from 'payload'
3
4
// --- reader plugin ---
5
6
export type ReaderPluginOptions = {
7
items: Array<{ name: string }>
8
}
9
10
export const readerPlugin = definePlugin<ReaderPluginOptions>({
11
slug: 'my-reader',
12
order: 10,
13
plugin: ({ config, items }) => ({
14
...config,
15
custom: {
16
...config.custom,
17
items: items.map((i) => i.name),
18
},
19
}),
20
})
21
22
declare module 'payload' {
23
interface RegisteredPlugins {
24
'my-reader': ReaderPluginOptions
25
}
26
}
27
28
// --- writer plugin (separate package) ---
29
30
export const writerPlugin = definePlugin({
31
slug: 'my-writer',
32
order: 1,
33
plugin: ({ config, plugins }) => {
34
// Runs before reader — mutates reader's options before reader executes
35
plugins['my-reader']?.options?.items.push({ name: 'injected-by-writer' })
36
return config
37
},
38
})
39
40
// --- payload.config.ts ---
41
plugins: [readerPlugin({ items: [{ name: 'user-provided' }] }), writerPlugin()]
42
// 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:

1
const hasSeo = config.plugins?.some((p) => p.slug === 'plugin-seo') ?? false

Or via the plugins map inside a definePlugin function:

1
plugin: ({ config, plugins }) => {
2
if (plugins['plugin-seo']) {
3
// plugin-seo is installed — safe to mutate its options
4
}
5
return config
6
}

Was this page helpful?

Next

Form Builder Plugin