feat: add internal plugin priority and slug api for cross-plugin discovery (#16244)

Adds a temporary, internal API for plugin execution ordering and
cross-plugin discovery. Plugins can now attach three optional properties
to their function:

- `priority` - controls execution order (ascending, default 0), so a
high-priority plugin is guaranteed to see config changes from all
lower-priority plugins
- `slug` - unique identifier so plugins can find each other in
`config.plugins` without importing each other. Useful for checking
within plugin A whether plugin B is installed
- `options` - exposes the plugin's closure args, allowing other plugins
to mutate them before the plugin executes (e.g. injecting tools into
plugin-mcp's options)

Marked as `@internal` so we can start using this across our own plugins
without committing to a public API yet.

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1214027832433527

Author: AlessioGr

packages/payload/src/config/build.ts

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

packages/payload/src/config/types.ts

@@ -143,7 +143,14 @@ type Prettify<T> = {
   [K in keyof T]: T[K]
 } & NonNullable<unknown>
 
-export type Plugin = (config: Config) => Config | Promise<Config>
+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
+  /** @internal Unique identifier for cross-plugin discovery via `config.plugins`. */
+  slug?: string
+}
 
 export type LivePreviewURLType = null | string | undefined
 

test/plugins/config.ts

@@ -1,3 +1,5 @@
+import type { Config, Plugin } from 'payload'
+
 import { fileURLToPath } from 'node:url'
 import path from 'path'
 
@@ -8,6 +10,58 @@ const dirname = path.dirname(filename)
 
 export const pagesSlug = 'pages'
 
+type ReaderPluginOptions = {
+  items: Array<{ name: string }>
+}
+
+/**
+ * High-priority plugin that reads both its own options and config.custom.
+ * Other plugins can inject additional items into its options via slug discovery.
+ */
+const readerPlugin = (pluginOptions: ReaderPluginOptions): Plugin => {
+  const plugin: Plugin = (config: Config): Config => ({
+    ...config,
+    custom: {
+      ...(config.custom || {}),
+      readerSawValue: (config.custom?.writerValue as string) ?? null,
+      readerItems: pluginOptions.items.map((i) => i.name),
+    },
+  })
+
+  plugin.slug = 'priority-reader'
+  plugin.priority = 10
+  plugin.options = pluginOptions
+
+  return plugin
+}
+
+/**
+ * Low-priority plugin that writes to config.custom and injects items
+ * into the reader plugin's options via slug discovery.
+ */
+const writerPlugin = (): Plugin => {
+  const plugin: Plugin = (config: Config): Config => {
+    const reader = config.plugins?.find((p) => p.slug === 'priority-reader')
+    if (reader?.options) {
+      const opts = reader.options as unknown as ReaderPluginOptions
+      opts.items.push({ name: 'injected-by-writer' })
+    }
+
+    return {
+      ...config,
+      custom: {
+        ...(config.custom || {}),
+        writerValue: 'written-by-low-priority',
+      },
+    }
+  }
+
+  plugin.priority = 1
+  plugin.slug = 'priority-writer'
+
+  return plugin
+}
+
 export default buildConfigWithDefaults({
   admin: {
     importMap: {
@@ -37,6 +91,9 @@ export default buildConfigWithDefaults({
         },
       ],
     }),
+    // Intentionally listed BEFORE the writer to verify priority sorting works
+    readerPlugin({ items: [{ name: 'user-provided' }] }),
+    writerPlugin(),
   ],
   onInit: async (payload) => {
     await payload.create({

test/plugins/int.spec.ts

@@ -31,4 +31,29 @@ describe('Collections - Plugins', () => {
 
     expect(id).toBeDefined()
   })
+
+  describe('plugin priority, slug, and options', () => {
+    it('should execute plugins sorted by priority regardless of array order', () => {
+      // The reader (priority 10) is listed BEFORE the writer (priority 1) in the array,
+      // but priority sorting ensures the writer runs first.
+      expect(payload.config.custom?.readerSawValue).toBe('written-by-low-priority')
+    })
+
+    it('should allow plugins to find each other by slug', () => {
+      const reader = payload.config.plugins?.find((p) => p.slug === 'priority-reader')
+      const writer = payload.config.plugins?.find((p) => p.slug === 'priority-writer')
+
+      expect(reader).toBeDefined()
+      expect(writer).toBeDefined()
+    })
+
+    it('should allow a plugin to mutate another plugin options via slug', () => {
+      // The writer (runs first) finds the reader by slug and pushes into its options.items.
+      // The reader (runs second) sees both the user-provided and injected items.
+      const items = payload.config.custom?.readerItems as string[]
+
+      expect(items).toContain('user-provided')
+      expect(items).toContain('injected-by-writer')
+    })
+  })
 })