feat: expand plugin API (#16247)

## Why
Payload's plugin system works but lacks built-in support for execution
ordering, cross-plugin discovery, and typed options. Plugin authors
manually attach metadata and consumers have no ergonomic way to find or
interact with other plugins. This PR adds a small, opt-in API layer on
top of the existing (config) => config contract.

## What
### definePlugin helper
Replaces boilerplate for published plugins. The plugin function receives
a single flat object with config, a plugins map, and user options spread
in:

```ts
import { definePlugin } from 'payload'

export const seoPlugin = definePlugin<SEOPluginOptions>({
  slug: 'plugin-seo',
  order: 10,
  plugin: ({ config, plugins, collections, generateTitle }) => ({
    ...config,
    // collections and generateTitle come from SEOPluginOptions
  }),
})
```

### Execution ordering via order
Plugins are sorted by order before execution (lower runs first, default
0). Array position is used as a tiebreaker.

```ts
plugins: [
  analyticsPlugin(), // order 10 — runs second
  basePlugin(),      // order 1  — runs first
]
```

### Typed plugins map for cross-plugin communication
Each definePlugin function receives a slug-keyed plugins map — no
imports needed:

```ts
plugin: ({ config, plugins }) => {
  const seo = plugins['plugin-seo']
  seo?.options?.collections.push('my-collection')
  return config
}
```

### RegisteredPlugins module augmentation
Plugin packages register their slug/options type for automatic type
safety:

```ts
declare module 'payload' {
  interface RegisteredPlugins {
    'plugin-seo': SEOPluginOptions
  }
}
```

## What's unchanged
The plain function form `(config) => ({ ...config })` still works and
always will. Everything above is opt-in.

Author: paulpopus

docs/plugins/plugin-api.mdx

@@ -0,0 +1,238 @@
+---
+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.
+
+<Banner type="info">
+  The API on this page is marked `@internal` while we finalize the design. It is
+  safe to use across Payload's own plugins, but the surface may change before
+  being declared stable.
+</Banner>
+
+## 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 any user-provided options spread directly in:
+
+```ts
+export const seoPlugin = definePlugin<SEOPluginOptions>({
+  slug: 'plugin-seo',
+  order: 10,
+  plugin: ({ config, plugins, collections }) => ({
+    ...config,
+    collections: [...(config.collections || []), seoCollection],
+  }),
+})
+```
+
+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` 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:
+
+```ts
+export const writerPlugin = definePlugin({
+  slug: 'my-writer',
+  order: 1,
+  plugin: ({ config, plugins }) => {
+    const seo = plugins['plugin-seo']
+    seo?.options?.collections.push('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, unknown>) => string
+}
+
+export const seoPlugin = definePlugin<SEOPluginOptions>({
+  slug: 'plugin-seo',
+  order: 10,
+  plugin: ({ config, collections }) => ({
+    ...config,
+    // extend config here
+  }),
+})
+
+// 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
+    plugins['plugin-seo']?.options?.collections.push('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<ReaderPluginOptions>({
+  slug: 'my-reader',
+  order: 10,
+  plugin: ({ config, items }) => ({
+    ...config,
+    custom: {
+      ...config.custom,
+      items: 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 — mutates reader's options before reader executes
+    plugins['my-reader']?.options?.items.push({ 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
+}
+```

packages/payload/src/config/build.ts

@@ -9,7 +9,7 @@ import { sanitizeConfig } from './sanitize.js'
  */
 export async function buildConfig(config: Config): Promise<SanitizedConfig> {
   if (Array.isArray(config.plugins)) {
-    const sorted = [...config.plugins].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0))
+    const sorted = [...config.plugins].sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
 
     for (const plugin of sorted) {
       config = await plugin(config)

packages/payload/src/config/definePlugin.ts

@@ -0,0 +1,75 @@
+import type { Config, Plugin, PluginsMap } from './types.js'
+
+function buildPluginsMap(plugins: Plugin[] | undefined): PluginsMap {
+  const map: Record<string, Plugin | undefined> = {}
+  if (plugins) {
+    for (const p of plugins) {
+      if (p.slug) {
+        map[p.slug] = p
+      }
+    }
+  }
+  return map as PluginsMap
+}
+
+/**
+ * Helper for authoring plugins with order, slug, and typed options.
+ * Eliminates boilerplate and ensures metadata is always set consistently.
+ *
+ * The `plugin` function receives a single object containing `config`, `plugins`
+ * (a slug-keyed map of other plugins), and any user-provided options spread in.
+ *
+ * @example
+ * // With options:
+ * export const seoPlugin = definePlugin<SEOPluginOptions>({
+ *   slug: 'plugin-seo',
+ *   order: 10,
+ *   plugin: ({ config, plugins, collections }) => ({ ...config }),
+ * })
+ *
+ * // Without options:
+ * export const myPlugin = definePlugin({
+ *   slug: 'my-plugin',
+ *   plugin: ({ config }) => ({ ...config }),
+ * })
+ */
+export function definePlugin(descriptor: {
+  order?: number
+  plugin: (args: { config: Config; plugins: PluginsMap }) => Config | Promise<Config>
+  slug?: string
+}): () => Plugin
+export function definePlugin<TOptions extends Record<string, unknown>>(descriptor: {
+  order?: number
+  plugin: (args: { config: Config; plugins: PluginsMap } & TOptions) => Config | Promise<Config>
+  slug?: string
+}): (options: TOptions) => Plugin
+export function definePlugin<TOptions extends Record<string, unknown>>(descriptor: {
+  order?: number
+  plugin: (args: { config: Config; plugins: PluginsMap } & TOptions) => Config | Promise<Config>
+  slug?: string
+}): (options?: TOptions) => Plugin {
+  return (options?: TOptions): Plugin => {
+    const pluginFn: Plugin = (config) => {
+      const plugins = buildPluginsMap(config.plugins)
+
+      const args = {
+        ...options,
+        config,
+        plugins,
+      } as { config: Config; plugins: PluginsMap } & TOptions
+
+      return descriptor.plugin(args)
+    }
+
+    pluginFn.options = options as Record<string, unknown>
+
+    if (descriptor.slug !== undefined) {
+      pluginFn.slug = descriptor.slug
+    }
+    if (descriptor.order !== undefined) {
+      pluginFn.order = descriptor.order
+    }
+
+    return pluginFn
+  }
+}

packages/payload/src/config/types.ts

@@ -51,6 +51,7 @@ import type {
   JobsConfig,
   KVAdapterResult,
   Payload,
+  RegisteredPlugins,
   RequestContext,
   SelectField,
   TypedUser,
@@ -147,11 +148,19 @@ export type Plugin = ((config: Config) => Config | Promise<Config>) & {
   /** @internal Plugin options exposed for cross-plugin mutation. */
   options?: Record<string, unknown>
   /** @internal Execution order - lower values run first. Defaults to 0. */
-  priority?: number
+  order?: number
   /** @internal Unique identifier for cross-plugin discovery via `config.plugins`. */
   slug?: string
 }
 
+/**
+ * A map of plugin slugs to Plugin instances, built from `config.plugins`.
+ * Registered slugs (via `RegisteredPlugins` module augmentation) return typed options.
+ */
+export type PluginsMap = {
+  [K in keyof RegisteredPlugins]: ({ options: RegisteredPlugins[K] } & Plugin) | undefined
+} & Record<string, Plugin | undefined>
+
 export type LivePreviewURLType = null | string | undefined
 
 export type LivePreviewConfig = {

packages/payload/src/index.ts

@@ -266,6 +266,21 @@ export interface UntypedPayloadTypes {
  */
 export interface GeneratedTypes {}
 
+/**
+ * Interface to be module-augmented by plugin packages.
+ * Maps plugin slug to plugin options type, enabling typed cross-plugin
+ * discovery via the `plugins` map passed to `definePlugin` functions.
+ *
+ * @example
+ * // In a plugin package's index.ts:
+ * declare module 'payload' {
+ *   interface RegisteredPlugins {
+ *     'plugin-seo': SEOPluginOptions
+ *   }
+ * }
+ */
+export interface RegisteredPlugins {}
+
 /**
  * Check if GeneratedTypes has been augmented (has any keys).
  */
@@ -1386,6 +1401,7 @@ export {
   type UnauthenticatedClientConfig,
 } from './config/client.js'
 export { defaults } from './config/defaults.js'
+export { definePlugin } from './config/definePlugin.js'
 
 export { type OrderableEndpointBody } from './config/orderable/index.js'
 export { sanitizeConfig } from './config/sanitize.js'