Skip to content

Commit aebbf75

Browse files
authored
fix: let plugins replace another plugin's options (#18762)
`definePlugin` now reads a plugin's `options` when the plugin runs, instead of the object it was created with. ### Why? Other plugins could only edit that object. Replacing it (`plugin.options = { ... }`) was silently ignored, and a plugin registered without options had no object to edit at all. _Written by AI_
1 parent 786dffb commit aebbf75

4 files changed

Lines changed: 61 additions & 9 deletions

File tree

‎docs/plugins/plugin-api.mdx‎

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -103,11 +103,11 @@ Settle on a convention so the ecosystem converges:
103103

104104
Plugins often need to be aware of each other. The pattern for this is:
105105

106-
1. A plugin with a `slug` exposes its `options` object — the same object passed at call time
107-
2. Another plugin finds it via the `plugins` map and mutates those options before the first plugin runs
108-
3. When the first plugin executes, it sees the mutated options
106+
1. A plugin with a `slug` exposes its `options` on the plugin function
107+
2. Another plugin finds it via the `plugins` map and mutates or replaces those options before the first plugin runs
108+
3. When the first plugin executes, it reads its current `options`, so it sees the changes
109109

110-
Since options are resolved before any plugin runs, this works cleanly without re-execution.
110+
Since a plugin reads its `options` when it runs, changes made by plugins with a lower `order` are picked up without re-execution.
111111

112112
### The `plugins` map
113113

@@ -119,7 +119,12 @@ export const writerPlugin = definePlugin({
119119
order: 1,
120120
plugin: ({ config, plugins }) => {
121121
const seo = plugins['plugin-seo']
122-
seo?.options?.collections.push('my-collection')
122+
if (seo) {
123+
seo.options = {
124+
...seo.options,
125+
collections: [...(seo.options?.collections ?? []), 'my-collection'],
126+
}
127+
}
123128
return config
124129
},
125130
})
@@ -163,7 +168,13 @@ export const writerPlugin = definePlugin({
163168
order: 1,
164169
plugin: ({ config, plugins }) => {
165170
// plugins['plugin-seo'] is typed — options is SEOPluginOptions
166-
plugins['plugin-seo']?.options?.collections.push('my-collection')
171+
const seo = plugins['plugin-seo']
172+
if (seo) {
173+
seo.options = {
174+
...seo.options,
175+
collections: [...(seo.options?.collections ?? []), 'my-collection'],
176+
}
177+
}
167178
return config
168179
},
169180
})
@@ -207,8 +218,17 @@ export const writerPlugin = definePlugin({
207218
slug: 'my-writer',
208219
order: 1,
209220
plugin: ({ config, plugins }) => {
210-
// Runs before reader — mutates reader's options before reader executes
211-
plugins['my-reader']?.options?.items.push({ name: 'injected-by-writer' })
221+
// Runs before reader — replaces reader's options before reader executes
222+
const reader = plugins['my-reader']
223+
if (reader) {
224+
reader.options = {
225+
...reader.options,
226+
items: [
227+
...(reader.options?.items ?? []),
228+
{ name: 'injected-by-writer' },
229+
],
230+
}
231+
}
212232
return config
213233
},
214234
})

‎packages/payload/src/config/definePlugin.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,12 @@ export function definePlugin<TOptions>(descriptor: {
5858
slug: string
5959
}): (options: TOptions) => Plugin {
6060
return (options?: TOptions): Plugin => {
61+
// Read `pluginFn.options` when the plugin runs, so other plugins can edit or replace it, even
62+
// when the plugin was registered without options
6163
const pluginFn: Plugin = (config) =>
6264
descriptor.plugin({
6365
config,
64-
options: options as TOptions,
66+
options: pluginFn.options as TOptions,
6567
plugins: buildPluginsMap(config.plugins),
6668
})
6769

‎test/plugins/config.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,11 @@ export type ReaderPluginOptions = {
1313
items: Array<{ name: string }>
1414
}
1515

16+
export type OptionalSettingsPluginOptions = { items: string[] } | undefined
17+
1618
declare module 'payload' {
1719
interface RegisteredPlugins {
20+
'optional-settings': OptionalSettingsPluginOptions
1821
'priority-reader': ReaderPluginOptions
1922
}
2023
}
@@ -36,6 +39,21 @@ const readerPlugin = definePlugin<ReaderPluginOptions>({
3639
}),
3740
})
3841

42+
/**
43+
* Plugin registered without options. The writer replaces its options with a new object.
44+
*/
45+
const optionalSettingsPlugin = definePlugin<OptionalSettingsPluginOptions>({
46+
slug: 'optional-settings',
47+
order: 10,
48+
plugin: ({ config, options }): Config => ({
49+
...config,
50+
custom: {
51+
...(config.custom || {}),
52+
optionalSettingsItems: options?.items ?? [],
53+
},
54+
}),
55+
})
56+
3957
/**
4058
* Plugin with order 1 (runs first) that writes to config.custom and injects items
4159
* into the reader plugin's options via typed slug discovery.
@@ -49,6 +67,11 @@ const writerPlugin = definePlugin({
4967
reader.options.items.push({ name: 'injected-by-writer' })
5068
}
5169

70+
const optionalSettings = plugins['optional-settings']
71+
if (optionalSettings) {
72+
optionalSettings.options = { items: ['set-by-writer'] }
73+
}
74+
5275
return {
5376
...config,
5477
custom: {
@@ -94,6 +117,7 @@ export default buildConfigWithDefaults({
94117
}),
95118
// Intentionally listed BEFORE the writer to verify order sorting works
96119
readerPlugin({ items: [{ name: 'user-provided' }] }),
120+
optionalSettingsPlugin(),
97121
writerPlugin(),
98122
],
99123
typescript: {

‎test/plugins/int.spec.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,12 @@ test.suite('Collections - Plugins', { config: './config.ts' }, () => {
4343
expect(items).toContain('injected-by-writer')
4444
})
4545

46+
test('should let a plugin replace the options of a plugin registered without options', ({
47+
payload,
48+
}) => {
49+
expect(payload.config.custom?.optionalSettingsItems).toEqual(['set-by-writer'])
50+
})
51+
4652
test('should expose typed options on plugins found by slug', ({ payload }) => {
4753
const reader = payload.config.plugins?.find((p) => p.slug === 'priority-reader')
4854

0 commit comments

Comments
 (0)