@payloadcms/codemod 4.0.0-internal.58473b9 → 4.0.0-internal.5d2e3d1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -2
- package/dist/registry.d.ts.map +1 -1
- package/dist/registry.js +6 -0
- package/dist/registry.js.map +1 -1
- package/dist/runbook/payload-v4-upgrade.md +2 -2
- package/dist/runbook/v4.mdx +398 -78
- package/dist/transforms/migrate-admin-context-properties/basic.input.js +32 -0
- package/dist/transforms/migrate-admin-context-properties/basic.input.js.map +1 -0
- package/dist/transforms/migrate-admin-context-properties/basic.output.js +30 -0
- package/dist/transforms/migrate-admin-context-properties/basic.output.js.map +1 -0
- package/dist/transforms/migrate-admin-context-properties/index.d.ts +3 -0
- package/dist/transforms/migrate-admin-context-properties/index.d.ts.map +1 -0
- package/dist/transforms/migrate-admin-context-properties/index.js +302 -0
- package/dist/transforms/migrate-admin-context-properties/index.js.map +1 -0
- package/dist/transforms/migrate-admin-context-properties/no-match.input.js +30 -0
- package/dist/transforms/migrate-admin-context-properties/no-match.input.js.map +1 -0
- package/dist/transforms/migrate-admin-context-properties/no-match.output.js +30 -0
- package/dist/transforms/migrate-admin-context-properties/no-match.output.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/basic.input.js +4 -0
- package/dist/transforms/migrate-displayed-field-value-args/basic.input.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/basic.output.js +8 -0
- package/dist/transforms/migrate-displayed-field-value-args/basic.output.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/index.d.ts +3 -0
- package/dist/transforms/migrate-displayed-field-value-args/index.d.ts.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/index.js +84 -0
- package/dist/transforms/migrate-displayed-field-value-args/index.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/namespace.input.js +4 -0
- package/dist/transforms/migrate-displayed-field-value-args/namespace.input.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/namespace.output.js +8 -0
- package/dist/transforms/migrate-displayed-field-value-args/namespace.output.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/no-match.input.js +4 -0
- package/dist/transforms/migrate-displayed-field-value-args/no-match.input.js.map +1 -0
- package/dist/transforms/migrate-displayed-field-value-args/no-match.output.js +4 -0
- package/dist/transforms/migrate-displayed-field-value-args/no-match.output.js.map +1 -0
- package/dist/transforms/rename-diff-value-props/basic.input.js +38 -0
- package/dist/transforms/rename-diff-value-props/basic.input.js.map +1 -0
- package/dist/transforms/rename-diff-value-props/basic.output.js +38 -0
- package/dist/transforms/rename-diff-value-props/basic.output.js.map +1 -0
- package/dist/transforms/rename-diff-value-props/index.d.ts +3 -0
- package/dist/transforms/rename-diff-value-props/index.d.ts.map +1 -0
- package/dist/transforms/rename-diff-value-props/index.js +328 -0
- package/dist/transforms/rename-diff-value-props/index.js.map +1 -0
- package/dist/transforms/rename-diff-value-props/no-match.input.js +8 -0
- package/dist/transforms/rename-diff-value-props/no-match.input.js.map +1 -0
- package/dist/upgrade/defaultTag.d.ts +1 -1
- package/dist/upgrade/defaultTag.js +2 -2
- package/dist/upgrade/defaultTag.js.map +1 -1
- package/dist/upgrade/prompt.js +3 -3
- package/dist/upgrade/prompt.js.map +1 -1
- package/package.json +9 -11
package/dist/runbook/v4.mdx
CHANGED
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: 3.0 to 4.0 Migration Guide
|
|
3
3
|
label: 3.0 to 4.0
|
|
4
|
-
order:
|
|
4
|
+
order: 20
|
|
5
5
|
desc: Upgrade guide for Payload 3.x projects migrating to 4.0.
|
|
6
6
|
keywords: local api, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
# Payload 3.0 to 4.0 Migration Guide
|
|
10
|
-
|
|
11
9
|
All breaking changes are listed below. If you encounter changes that are not explicitly listed here, please consider contributing to this documentation by submitting a PR.
|
|
12
10
|
|
|
13
11
|
## Codemod
|
|
@@ -22,6 +20,30 @@ The codemod is idempotent and safe to run on a partially-migrated project.
|
|
|
22
20
|
|
|
23
21
|
## Breaking Changes
|
|
24
22
|
|
|
23
|
+
### Form-state data utilities are renamed
|
|
24
|
+
|
|
25
|
+
The shared form-state utilities exported from `payload/shared` now explicitly name their source:
|
|
26
|
+
|
|
27
|
+
| Old name | New name |
|
|
28
|
+
| ---------------------- | ----------------------------- |
|
|
29
|
+
| `reduceFieldsToValues` | `getDataFromFormState` |
|
|
30
|
+
| `getSiblingData` | `getSiblingDataFromFormState` |
|
|
31
|
+
|
|
32
|
+
Update imports and calls. Their arguments are unchanged:
|
|
33
|
+
|
|
34
|
+
```diff
|
|
35
|
+
-import { reduceFieldsToValues, getSiblingData } from 'payload/shared'
|
|
36
|
+
+import { getDataFromFormState, getSiblingDataFromFormState } from 'payload/shared'
|
|
37
|
+
|
|
38
|
+
-const data = reduceFieldsToValues(fields, true)
|
|
39
|
+
+const data = getDataFromFormState(fields, true)
|
|
40
|
+
|
|
41
|
+
-const siblingData = getSiblingData(fields, 'items.0.title')
|
|
42
|
+
+const siblingData = getSiblingDataFromFormState(fields, 'items.0.title')
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The form-context methods `useForm().getData()` and `useForm().getSiblingData()` keep their names.
|
|
46
|
+
|
|
25
47
|
### Payload request creation is consolidated
|
|
26
48
|
|
|
27
49
|
Payload request creation now uses `createPayloadRequest` for local contexts and `createPayloadRequestFromWebRequest` to convert a Web `Request`. Admin context setup is exposed as `initAdminContext`.
|
|
@@ -122,9 +144,15 @@ A token is also rejected if its `collection` is not auth-enabled or has `disable
|
|
|
122
144
|
|
|
123
145
|
See [Token Data](../authentication/token-data) for the full token data shape.
|
|
124
146
|
|
|
125
|
-
###
|
|
147
|
+
### Sessions track their refreshes
|
|
148
|
+
|
|
149
|
+
Auth collections with `useSessions` (the default) now store two more fields on each session, `refreshCount` and `refreshedAt`. [Refresh tokens](../authentication/overview#refresh-tokens) use them to tell the latest refresh token apart from older ones.
|
|
150
|
+
|
|
151
|
+
On SQL adapters this adds two columns to each `<collection>_sessions` table, so existing projects need a database migration. In development the schema is pushed automatically; in production, generate a migration with `payload migrate:create` and run `payload migrate`. Existing sessions keep working, since an empty `refreshCount` counts as `0`. MongoDB needs no migration.
|
|
126
152
|
|
|
127
|
-
Local API
|
|
153
|
+
### Local API access is now enforced by default #overrideaccess-now-defaults-to-false-on-local-api-operations
|
|
154
|
+
|
|
155
|
+
`overrideAccess` now defaults to `false` on Local API operations, so omitting it respects Access Control instead. Operations that do not expose `overrideAccess`, and operations such as `resetPassword` where it was already required or did not default to `true`, are unaffected by this change.
|
|
128
156
|
|
|
129
157
|
```diff
|
|
130
158
|
const posts = await payload.find({
|
|
@@ -156,7 +184,32 @@ Run a typecheck after the codemod. Three patterns it cannot resolve:
|
|
|
156
184
|
|
|
157
185
|
`payload.jobs.queue`, `run`, `runByID`, `cancel`, and `cancelByID` now also default `overrideAccess` to `false`. The option remains optional, but omitting it runs the corresponding `jobs.access.queue`, `jobs.access.run`, or `jobs.access.cancel` function. The codemod adds `overrideAccess: true` to these calls—including zero-argument `payload.jobs.run()` calls—to preserve Payload 3 behavior for review.
|
|
158
186
|
|
|
159
|
-
###
|
|
187
|
+
### On-demand validation adds a `validate` operation
|
|
188
|
+
|
|
189
|
+
The `Operation` type now includes `validate`. The `operation` argument for collection, global, and field `beforeValidate` and `beforeChange` hooks also includes `validate`.
|
|
190
|
+
|
|
191
|
+
On-demand validation runs these hooks without saving the candidate. Update exhaustive operation checks and skip external side effects that should only run during `create` or `update`:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
import type { CollectionBeforeChangeHook } from 'payload'
|
|
195
|
+
|
|
196
|
+
const syncCustomer: CollectionBeforeChangeHook = async ({
|
|
197
|
+
data,
|
|
198
|
+
operation,
|
|
199
|
+
}) => {
|
|
200
|
+
if (operation === 'validate') {
|
|
201
|
+
return data
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
await syncCustomerWithStripe(data)
|
|
205
|
+
|
|
206
|
+
return data
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Sanitized collection and global access types now require a `validate` key. Payload supplies this key during configuration sanitization and uses `update` access by default. Code that constructs a sanitized access object directly must add the key.
|
|
211
|
+
|
|
212
|
+
### Access Control callbacks now receive document slugs
|
|
160
213
|
|
|
161
214
|
Collection and Global Access Control callback arguments now include the document's `slug`. This additive property is unlikely to affect most projects, but code that manually invokes access callbacks or `executeAccess` must now pass `slug`. Code that validates, enumerates, or compares the exact callback argument shape may also need updating.
|
|
162
215
|
|
|
@@ -246,7 +299,7 @@ Payload adds built-in command import references to `cli.commands` while sanitizi
|
|
|
246
299
|
|
|
247
300
|
See the [Payload CLI documentation](../configuration/cli) for the complete API.
|
|
248
301
|
|
|
249
|
-
###
|
|
302
|
+
### Legacy migration CLI export removed
|
|
250
303
|
|
|
251
304
|
The undocumented `migrateCLI` export has been removed. It accepted an already-sanitized config, a minimist-shaped `parsedArgs` object, and a special `migrationDir` override. This duplicated migration command registration and kept the old argument format alive after the main CLI moved to Commander.
|
|
252
305
|
|
|
@@ -275,7 +328,7 @@ The spawned CLI discovers the Payload config from `cwd` or `PAYLOAD_CONFIG_PATH`
|
|
|
275
328
|
|
|
276
329
|
`generateTypes` now returns `{ types, outputFile, written }` instead of returning the generated source directly when using `returnString: true`. `generateImportMap` now returns `{ outputFile, written }`, and `payload.db.generateSchema()` returns `{ outputFile }`. Code that ignores these return values does not need to change.
|
|
277
330
|
|
|
278
|
-
### Default query depth
|
|
331
|
+
### Default query depth has been reduced
|
|
279
332
|
|
|
280
333
|
Queries that omit `depth` now populate one relationship level instead of two. This reduces database work and response size by default.
|
|
281
334
|
|
|
@@ -350,7 +403,7 @@ export const Posts: CollectionConfig = {
|
|
|
350
403
|
}
|
|
351
404
|
```
|
|
352
405
|
|
|
353
|
-
### Authorship
|
|
406
|
+
### Authorship is now enabled by default
|
|
354
407
|
|
|
355
408
|
Collections and globals now track authorship by default: Payload injects `createdBy` and `updatedBy` polymorphic relationship fields (related to every auth-enabled collection) and stamps them from `req.user` on each write. Previously there was no authorship tracking; you now opt out with `authorship: false`.
|
|
356
409
|
|
|
@@ -389,7 +442,7 @@ The `admin.enableListViewSelectAPI` Collection Config property has been removed.
|
|
|
389
442
|
|
|
390
443
|
If you previously set `admin.enableListViewSelectAPI: true`, remove the property — the behavior is now default. The `migrate-list-view-select-api` transform in `@payloadcms/codemod` handles this automatically.
|
|
391
444
|
|
|
392
|
-
###
|
|
445
|
+
### Global component slots now match Collections
|
|
393
446
|
|
|
394
447
|
Global configs now use the same `admin.components` shape as Collections. The Edit View slot container is renamed from `elements` to `edit`, the `Description` slot is hoisted to top-level `admin.components.Description`, and `editMenuItems` is now supported.
|
|
395
448
|
|
|
@@ -417,7 +470,7 @@ Globals also now support custom views with arbitrary keys under `admin.component
|
|
|
417
470
|
|
|
418
471
|
This change is auto-migrated by the `globals-components-edit` codemod.
|
|
419
472
|
|
|
420
|
-
###
|
|
473
|
+
### Dynamic selection replaces static forced selection
|
|
421
474
|
|
|
422
475
|
The static `forceSelect` config has been removed. Each Collection and Global now accepts a top-level `select` function that receives the current `operation`, `req`, and the caller's `select`, and returns the final `select` to use. Returning `undefined` leaves the caller's `select` unchanged.
|
|
423
476
|
|
|
@@ -442,9 +495,9 @@ The same change applies to Globals.
|
|
|
442
495
|
|
|
443
496
|
Run `npx @payloadcms/codemod --transform migrate-force-select` to migrate automatically. The codemod handles object-literal `forceSelect` values, including nested ones (which previously deep-merged) — those are rewritten to call `deepMergeSimple` from `payload/shared`, with the import added automatically. Non-literal values, configs that already define a sibling `select`, and unsupported member kinds are surfaced as notes for manual review.
|
|
444
497
|
|
|
445
|
-
####
|
|
498
|
+
#### API tab visibility now uses a condition
|
|
446
499
|
|
|
447
|
-
Use the existing `admin.components.views.edit.api.tab.condition` to hide the API tab instead.
|
|
500
|
+
`admin.hideAPIURL` has been removed from Collections and Globals. Use the existing `admin.components.views.edit.api.tab.condition` to hide the API tab instead.
|
|
448
501
|
|
|
449
502
|
```diff
|
|
450
503
|
// collections/Posts.ts
|
|
@@ -472,7 +525,7 @@ export const PostsCollection: CollectionConfig = {
|
|
|
472
525
|
|
|
473
526
|
Run `npx @payloadcms/codemod --transform remove-hide-api-url` to migrate automatically.
|
|
474
527
|
|
|
475
|
-
### Aliased
|
|
528
|
+
### Aliased UI and Next.js re-exports have been removed
|
|
476
529
|
|
|
477
530
|
Several types and utilities that were re-exported from `@payloadcms/ui` and `@payloadcms/next/utilities` for backwards compatibility have been removed. The canonical exports live in `payload` and `payload/shared`; import directly from there.
|
|
478
531
|
|
|
@@ -558,7 +611,40 @@ To migrate automatically, there's a codemod for this change available by running
|
|
|
558
611
|
npx @payloadcms/codemod --transform migrate-field-component-types
|
|
559
612
|
```
|
|
560
613
|
|
|
561
|
-
### `
|
|
614
|
+
### Diff component props `comparisonValue` and `versionValue` renamed to `valueFrom` and `valueTo`
|
|
615
|
+
|
|
616
|
+
Custom Diff Components (`admin.components.Diff`) receive the two field values being compared as `valueFrom` and `valueTo`. The `comparisonValue` and `versionValue` props have been removed from `FieldDiffClientProps` and `FieldDiffServerProps`, including every field-specific variant such as `TextFieldDiffClientProps`.
|
|
617
|
+
|
|
618
|
+
| Old prop | New prop | Description |
|
|
619
|
+
| ----------------- | ----------- | ------------------------------------------------ |
|
|
620
|
+
| `comparisonValue` | `valueFrom` | Field value from the version being compared from |
|
|
621
|
+
| `versionValue` | `valueTo` | Field value from the version being compared to |
|
|
622
|
+
|
|
623
|
+
```diff
|
|
624
|
+
import type { TextFieldDiffClientProps } from 'payload'
|
|
625
|
+
import type React from 'react'
|
|
626
|
+
|
|
627
|
+
export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
|
|
628
|
+
- comparisonValue,
|
|
629
|
+
- versionValue,
|
|
630
|
+
+ valueFrom,
|
|
631
|
+
+ valueTo,
|
|
632
|
+
}) => {
|
|
633
|
+
// ...
|
|
634
|
+
}
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
#### Codemod
|
|
638
|
+
|
|
639
|
+
To migrate automatically, there's a codemod for this change available by running:
|
|
640
|
+
|
|
641
|
+
```bash
|
|
642
|
+
npx @payloadcms/codemod --transform rename-diff-value-props
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
The codemod updates functions whose props are typed with a Diff props or component type imported from `payload` (e.g. `TextFieldDiffClientProps`), or with a type in the same file built from one. It renames destructured props and reads such as `props.comparisonValue`. Untyped components and props passed on to other components (e.g. `<OtherDiff comparisonValue={...} />`) aren't changed automatically; the codemod prints a note for each leftover in files that import a Diff type.
|
|
646
|
+
|
|
647
|
+
### Default value functions can now return promises ([#17522](https://github.com/payloadcms/payload/pull/17522))
|
|
562
648
|
|
|
563
649
|
The exported `DefaultValue` type's function variant previously declared a synchronous-only return type (`SerializableValue`), even though Payload has always awaited the result of a `defaultValue` function at runtime. The type now correctly reflects this and allows `Promise<SerializableValue> | SerializableValue`.
|
|
564
650
|
|
|
@@ -620,7 +706,7 @@ const interfaceName = global.typescript?.interface
|
|
|
620
706
|
|
|
621
707
|
Properties filled during sanitization, including `_sanitized`, `admin`, `custom`, `label`, standard access functions, hook arrays, endpoints, and flattened fields, remain required. Use `GlobalConfig` for input and `SanitizedGlobalConfig` after sanitization.
|
|
622
708
|
|
|
623
|
-
### User types
|
|
709
|
+
### User types have been consolidated
|
|
624
710
|
|
|
625
711
|
Payload's user types have been consolidated so each one has a clear job. This completes a cleanup already planned in 3.x: `UntypedUser` was deprecated for removal in 4.0, and `TypedUser` was marked to be renamed to `User` in 4.0.
|
|
626
712
|
|
|
@@ -686,7 +772,7 @@ If the field name is dynamic (configurable at runtime), index through `Record<st
|
|
|
686
772
|
const value = (user as Record<string, unknown>)[fieldNameFromConfig]
|
|
687
773
|
```
|
|
688
774
|
|
|
689
|
-
###
|
|
775
|
+
### Plugins now infer generated types automatically
|
|
690
776
|
|
|
691
777
|
The `<ConfigType>` type parameter on `multiTenantPlugin` and `searchPlugin` — and on `MultiTenantPluginConfig` / `SearchPluginConfig` — has been removed. It only existed to override the `user` / `locale` types, which Payload now infers from your generated types automatically: `userHasAccessToAllTenants` receives the generated `User`, and `search`'s `skipSync` callback receives `TypedLocale | undefined`.
|
|
692
778
|
|
|
@@ -697,9 +783,9 @@ Drop the type argument — your callbacks are typed correctly without it.
|
|
|
697
783
|
+ multiTenantPlugin({ ... })
|
|
698
784
|
```
|
|
699
785
|
|
|
700
|
-
###
|
|
786
|
+
### Plugin definitions now require a slug and named options
|
|
701
787
|
|
|
702
|
-
|
|
788
|
+
The experimental `definePlugin` helper now requires a `slug` and passes plugin options through a named `options` argument:
|
|
703
789
|
|
|
704
790
|
- **`slug` is now required.** It registers the plugin in the `plugins` map for cross-plugin discovery. Add one to every `definePlugin` call.
|
|
705
791
|
- **Options are a named `options` argument.** They were previously spread into the `plugin` callback's args alongside `config` and `plugins`; they're now under a single `options` property. `TOptions` is also no longer constrained to `Record<string, unknown>`, so `interface` and generic option types work.
|
|
@@ -713,9 +799,9 @@ export const myPlugin = definePlugin<MyPluginOptions>({
|
|
|
713
799
|
})
|
|
714
800
|
```
|
|
715
801
|
|
|
716
|
-
###
|
|
802
|
+
### Admin routing is now framework-agnostic
|
|
717
803
|
|
|
718
|
-
`@payloadcms/ui` no longer depends on `next` directly. Custom admin components (field components, custom views, plugins) that previously imported router hooks or the `Link` component from `next/*` must now import the framework-agnostic equivalents from `@payloadcms/ui`. Behavior is identical when running on Next.js — the `NextRouterAdapter` shipped by `@payloadcms/next` wires `next/navigation` hooks and `next/link` into the same context — but
|
|
804
|
+
`@payloadcms/ui` no longer depends on `next` directly. Custom admin components (field components, custom views, plugins) that previously imported router hooks or the `Link` component from `next/*` must now import the framework-agnostic equivalents from `@payloadcms/ui`. Behavior is identical when running on Next.js — the `NextRouterAdapter` shipped by `@payloadcms/next` wires `next/navigation` hooks and `next/link` into the same context — but UI code can now also run on non-Next adapters such as TanStack Start without modification.
|
|
719
805
|
|
|
720
806
|
**Hooks** — import from `@payloadcms/ui` instead of `next/navigation`:
|
|
721
807
|
|
|
@@ -767,7 +853,7 @@ If you were relying on Next-specific extras like `prefetch()` on the router inst
|
|
|
767
853
|
/>
|
|
768
854
|
```
|
|
769
855
|
|
|
770
|
-
###
|
|
856
|
+
### Next.js subpath exports have moved to the UI package
|
|
771
857
|
|
|
772
858
|
The `./client`, `./rsc`, and `./templates` subpath exports on `@payloadcms/next` were thin re-exports of components that now live in `@payloadcms/ui`. All admin elements (DocumentHeader, FormHeader, HierarchyTypeField, Logo, Nav) and templates (DefaultTemplate, MinimalTemplate) have been relocated to `@payloadcms/ui` and no longer depend on `next/*` modules. Import them directly from the canonical source.
|
|
773
859
|
|
|
@@ -805,7 +891,7 @@ If you reference any of these components by string path in your Payload config (
|
|
|
805
891
|
|
|
806
892
|
Run `npx @payloadcms/codemod --transform migrate-next-subpath-exports` to migrate automatically. It rewrites both `import` declarations and string component paths.
|
|
807
893
|
|
|
808
|
-
###
|
|
894
|
+
### Document title state has moved to its own hook
|
|
809
895
|
|
|
810
896
|
For performance reasons, the document title state has been split out of `DocumentInfoContext` into its own `DocumentTitleContext`. Access it through the `useDocumentTitle` hook, which exposes the same `title` and `setDocumentTitle` API. Components that subscribed to `useDocumentInfo` solely for the title will no longer re-render when unrelated document state changes.
|
|
811
897
|
|
|
@@ -825,7 +911,43 @@ If you only used `useDocumentInfo` for `title` / `setDocumentTitle`, drop the im
|
|
|
825
911
|
|
|
826
912
|
Run `npx @payloadcms/codemod --transform migrate-document-title-context` to migrate automatically. The codemod splits mixed destructures, removes the `useDocumentInfo` import when no other properties are still used, and preserves any rename aliases (e.g. `{ title: docTitle }`).
|
|
827
913
|
|
|
828
|
-
### `
|
|
914
|
+
### `Form` makes its own form-state requests
|
|
915
|
+
|
|
916
|
+
`Form` owns server form-state requests after field changes and successful saves. Document forms derive their request information from the surrounding document and operation providers. Nested forms identify their schema with `schemaPath`; bulk forms restrict their fields with `select`, and widget forms identify their entity with `widgetSlug`.
|
|
917
|
+
|
|
918
|
+
Remove callbacks that fetch and return server form state:
|
|
919
|
+
|
|
920
|
+
```diff
|
|
921
|
+
-const onChange = async ({ formState, submitted }) => {
|
|
922
|
+
- const { state } = await getFormState({
|
|
923
|
+
- collectionSlug,
|
|
924
|
+
- docPermissions,
|
|
925
|
+
- docPreferences: await getDocPreferences(),
|
|
926
|
+
- formState,
|
|
927
|
+
- operation: 'update',
|
|
928
|
+
- schemaPath,
|
|
929
|
+
- signal: controller.signal,
|
|
930
|
+
- skipValidation: !submitted,
|
|
931
|
+
- })
|
|
932
|
+
- return state
|
|
933
|
+
-}
|
|
934
|
+
-
|
|
935
|
+
-<Form initialState={initialState} onChange={[onChange]}>
|
|
936
|
+
+<Form initialState={initialState} schemaPath={schemaPath}>
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
A document's main form uses `isDocumentForm` and does not need `schemaPath`. It also owns document locking, stale-data detection, permission refreshes and preview URLs. Pass persistent read-only state with `readOnly`; temporary `disabled` or processing state does not make fields read-only on the server.
|
|
940
|
+
|
|
941
|
+
Plain custom forms without `isDocumentForm`, `schemaPath` or `widgetSlug` remain local, even when they receive `initialState` or are rendered inside a document provider. Initial state continues to be built before rendering the form.
|
|
942
|
+
|
|
943
|
+
BREAKING CHANGES:
|
|
944
|
+
|
|
945
|
+
- The return values of `onChange` and `onSuccess` are ignored. Use them for side effects only.
|
|
946
|
+
- `onChange` receives the merged state after an edit refresh or local submit validation, including invalid validation results. Validation notifications have `submitted: true`.
|
|
947
|
+
- Schema-backed forms with a local `onSubmit` validate on the server before committing. Remove `beforeSubmit` callbacks whose only purpose is fetching server form state. Invalid state or a validation request failure prevents the local commit.
|
|
948
|
+
- After a successful save, `Form` refreshes permissions and state before calling `onSuccess`. Creates skip the state refresh because they replace the form. A failed refresh does not change the successful save outcome or suppress `onSuccess`.
|
|
949
|
+
|
|
950
|
+
### Locale hooks can now return null
|
|
829
951
|
|
|
830
952
|
The return type of `useLocale` is now `Locale | null`. It returns `null` when localization is disabled or configured without any locales. In Payload 3, the hook was typed as `Locale` and returned an empty object when localization was unavailable.
|
|
831
953
|
|
|
@@ -855,7 +977,51 @@ When a missing locale is already valid for the receiving API, optional chaining
|
|
|
855
977
|
const locale = useLocale()?.code
|
|
856
978
|
```
|
|
857
979
|
|
|
858
|
-
###
|
|
980
|
+
### `readOnly` removed from the `useField` return type
|
|
981
|
+
|
|
982
|
+
The deprecated `readOnly` property has been removed from `FieldType`, the object returned by `useField`. `useField` already stopped returning it in 3.x, so it was always `undefined` at runtime.
|
|
983
|
+
|
|
984
|
+
Read `readOnly` from your field component's props instead:
|
|
985
|
+
|
|
986
|
+
```diff
|
|
987
|
+
'use client'
|
|
988
|
+
import type { TextFieldClientComponent } from 'payload'
|
|
989
|
+
import { useField } from '@payloadcms/ui'
|
|
990
|
+
|
|
991
|
+
-export const MyField: TextFieldClientComponent = ({ path }) => {
|
|
992
|
+
- const { readOnly, value } = useField({ path })
|
|
993
|
+
+export const MyField: TextFieldClientComponent = ({ path, readOnly }) => {
|
|
994
|
+
+ const { value } = useField({ path })
|
|
995
|
+
```
|
|
996
|
+
|
|
997
|
+
### Deprecated `TableColumnsProvider` props removed
|
|
998
|
+
|
|
999
|
+
The following deprecated props have been removed from `TableColumnsProvider` and its `TableColumnsProviderProps` type:
|
|
1000
|
+
|
|
1001
|
+
- `docs`
|
|
1002
|
+
- `enableRowSelections`
|
|
1003
|
+
- `listPreferences`
|
|
1004
|
+
- `preferenceKey`
|
|
1005
|
+
- `renderRowTypes`
|
|
1006
|
+
- `setTable`
|
|
1007
|
+
- `sortColumnProps`
|
|
1008
|
+
- `tableAppearance`
|
|
1009
|
+
|
|
1010
|
+
`TableColumnsProvider` has ignored these props since 3.26.0, when column state moved to the URL. Remove them where you render the provider. It now only accepts `children`, `collectionSlug`, `columnState`, and `LinkedCellOverride`.
|
|
1011
|
+
|
|
1012
|
+
```diff
|
|
1013
|
+
<TableColumnsProvider
|
|
1014
|
+
collectionSlug={collectionSlug}
|
|
1015
|
+
columnState={columnState}
|
|
1016
|
+
- enableRowSelections
|
|
1017
|
+
- preferenceKey={preferenceKey}
|
|
1018
|
+
- tableAppearance="condensed"
|
|
1019
|
+
>
|
|
1020
|
+
{children}
|
|
1021
|
+
</TableColumnsProvider>
|
|
1022
|
+
```
|
|
1023
|
+
|
|
1024
|
+
### Rich text adapters no longer expose translations
|
|
859
1025
|
|
|
860
1026
|
The `i18n` property on `RichTextAdapter` (and its return type from adapter provider functions) has been removed. It was deprecated in v3 in favour of merging translations directly into `config.i18n.translations` inside the adapter provider.
|
|
861
1027
|
|
|
@@ -912,11 +1078,63 @@ export const MyFeature = createServerFeature({
|
|
|
912
1078
|
|
|
913
1079
|
If an affected adapter or feature performs asynchronous work, move that work to an asynchronous plugin before config sanitization or to a runtime hook. Projects that only use `buildConfig(...)` and `lexicalEditor(...)` normally are not affected; `buildConfig` remains asynchronous.
|
|
914
1080
|
|
|
915
|
-
###
|
|
1081
|
+
### Transaction requests now use a single identifier property
|
|
916
1082
|
|
|
917
1083
|
The `transactionIDPromise` property on `PayloadRequest` has been removed. It was deprecated and unused — `transactionID` (which already supports `Promise<number | string>`) is the correct property to use for both resolved values and pending transactions.
|
|
918
1084
|
|
|
919
|
-
###
|
|
1085
|
+
### `headers` and `languageCode` removed from `AdminContext`
|
|
1086
|
+
|
|
1087
|
+
The `headers` and `languageCode` properties have been removed from `AdminContext`, the object returned by `initAdminContext`. Both duplicated values that are already available on `req`:
|
|
1088
|
+
|
|
1089
|
+
```diff
|
|
1090
|
+
const context = await initAdminContext(args)
|
|
1091
|
+
|
|
1092
|
+
-const userAgent = context.headers.get('user-agent')
|
|
1093
|
+
+const userAgent = context.req.headers.get('user-agent')
|
|
1094
|
+
|
|
1095
|
+
-const languageCode = context.languageCode
|
|
1096
|
+
+const languageCode = context.req.i18n.language
|
|
1097
|
+
```
|
|
1098
|
+
|
|
1099
|
+
`req.i18n.language` is typed as `string`. Cast it to `AcceptedLanguages` if you need the narrower type.
|
|
1100
|
+
|
|
1101
|
+
`languageCode` has also been removed from `PartialAdminContext`. Use `i18n.language` instead. `getRootLayoutData` from `@payloadcms/ui` no longer accepts `headers` or `languageCode` and reads both from `req`.
|
|
1102
|
+
|
|
1103
|
+
#### Codemod
|
|
1104
|
+
|
|
1105
|
+
To migrate automatically, run:
|
|
1106
|
+
|
|
1107
|
+
```bash
|
|
1108
|
+
npx @payloadcms/codemod --transform migrate-admin-context-properties
|
|
1109
|
+
```
|
|
1110
|
+
|
|
1111
|
+
The codemod rewrites property reads and destructures on `initAdminContext()` results and on parameters or variables typed as `AdminContext` or `PartialAdminContext`. It also updates `Pick<AdminContext, ...>` and `AdminContext['...']` types and drops both arguments from `getRootLayoutData()` calls. Element access such as `context['headers']`, and contexts passed through your own wrapper functions, are left unchanged for manual migration.
|
|
1112
|
+
|
|
1113
|
+
### `DiffMethod` type removed
|
|
1114
|
+
|
|
1115
|
+
The deprecated `DiffMethod` type has been removed from `payload`. It mirrored an enum from `react-diff-viewer-continued`, which Payload no longer depends on. Remove any imports of `DiffMethod`.
|
|
1116
|
+
|
|
1117
|
+
### `diffMethod` prop removed from Diff components
|
|
1118
|
+
|
|
1119
|
+
Custom Diff components (`admin.components.Diff`) no longer receive a `diffMethod` prop. It has been removed from `FieldDiffClientProps` and every field-specific variant like `TextFieldDiffClientProps`. Payload always passed the same `'diffWordsWithSpace'` value, so the prop carried no information. Each Diff component handles its own diffing.
|
|
1120
|
+
|
|
1121
|
+
Remove `diffMethod` from your props. If you passed it on to a diffing utility, pass `'diffWordsWithSpace'` directly instead:
|
|
1122
|
+
|
|
1123
|
+
```diff
|
|
1124
|
+
export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
|
|
1125
|
+
- diffMethod,
|
|
1126
|
+
valueFrom,
|
|
1127
|
+
valueTo,
|
|
1128
|
+
}) => {
|
|
1129
|
+
```
|
|
1130
|
+
|
|
1131
|
+
### `root` removed from the `Endpoint` type
|
|
1132
|
+
|
|
1133
|
+
The deprecated `root` property has been removed from the `Endpoint` type. It has been typed as `never` since 3.0, so it couldn't be set, and Payload ignored it.
|
|
1134
|
+
|
|
1135
|
+
To serve a route outside of `routes.api`, add it to your app directly, e.g. as a [Next.js route handler](https://nextjs.org/docs/app/api-reference/file-conventions/route).
|
|
1136
|
+
|
|
1137
|
+
### Collection after-operation hooks no longer report read operations
|
|
920
1138
|
|
|
921
1139
|
The deprecated `'read'` value for the `operation` argument of collection `afterOperation` hooks has been removed. Payload has not dispatched `afterOperation` with `operation: 'read'` for some time — the `find` and `findByID` operations report their own names (`'find'` and `'findByID'`) instead.
|
|
922
1140
|
|
|
@@ -939,14 +1157,14 @@ Run `npx @payloadcms/codemod --transform migrate-after-operation-read` to migrat
|
|
|
939
1157
|
|
|
940
1158
|
The `operation: 'read'` value on the `beforeOperation` hook is unchanged.
|
|
941
1159
|
|
|
942
|
-
###
|
|
1160
|
+
### Static configuration defaults have been removed ([#17103](https://github.com/payloadcms/payload/pull/17103))
|
|
943
1161
|
|
|
944
|
-
The defaults object exported from payload has been removed. It was deprecated because it was a single shared object and mutating it (or any config that used it as a base) leaked changes into every other consumer of the defaults.
|
|
1162
|
+
The `defaults` object exported from `payload` has been removed. It was deprecated because it was a single shared object and mutating it (or any config that used it as a base) leaked changes into every other consumer of the defaults.
|
|
945
1163
|
|
|
946
1164
|
If you depended on reading a specific default value at runtime, read it from the sanitized config returned by buildConfig (or payload.config) instead of from the static defaults object.
|
|
947
1165
|
Alternatively, you can call `addDefaultsToConfig` to get the unsanitized config but populated with the default properties.
|
|
948
1166
|
|
|
949
|
-
###
|
|
1167
|
+
### Import and export field callbacks have moved to hooks
|
|
950
1168
|
|
|
951
1169
|
The `toCSV` and `fromCSV` field options in `custom['plugin-import-export']` have been removed. Use `hooks.beforeExport` and `hooks.beforeImport` instead — they work for both CSV and JSON formats.
|
|
952
1170
|
|
|
@@ -987,7 +1205,7 @@ The `fromCSV` → `hooks.beforeImport` change is non-breaking for the `data` par
|
|
|
987
1205
|
|
|
988
1206
|
Run `npx @payloadcms/codemod --transform migrate-import-export-hooks` to migrate automatically. The codemod moves the function values into the correct hook positions and merges with any existing `hooks` object. Review argument names in the migrated functions — `row` references must be renamed to `siblingData` and `doc` references renamed to `data`.
|
|
989
1207
|
|
|
990
|
-
###
|
|
1208
|
+
### Database adapter types now use the main package exports
|
|
991
1209
|
|
|
992
1210
|
The `/types` subpath export has been removed from all Drizzle-based database adapter packages. All types are available directly from the main package entry point.
|
|
993
1211
|
|
|
@@ -1025,19 +1243,30 @@ If you use a `declare module` augmentation to extend `GeneratedDatabaseSchema` (
|
|
|
1025
1243
|
|
|
1026
1244
|
Run `npx @payloadcms/codemod --transform migrate-db-types-subpath` to migrate automatically. The codemod handles import declarations, re-export declarations, and `declare module` augmentations.
|
|
1027
1245
|
|
|
1028
|
-
###
|
|
1246
|
+
### `findMigrationDir` removed from `@payloadcms/drizzle`
|
|
1247
|
+
|
|
1248
|
+
The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/drizzle`. Import it from `payload` instead:
|
|
1029
1249
|
|
|
1030
|
-
|
|
1250
|
+
```diff
|
|
1251
|
+
- import { findMigrationDir } from '@payloadcms/drizzle'
|
|
1252
|
+
+ import { findMigrationDir } from 'payload'
|
|
1253
|
+
```
|
|
1031
1254
|
|
|
1032
|
-
### Minimum supported
|
|
1255
|
+
### Minimum supported Node.js version is now 24.22.1 ([#16540](https://github.com/payloadcms/payload/pull/16540))
|
|
1033
1256
|
|
|
1034
|
-
|
|
1257
|
+
The minimum supported Node.js version is now **24.22.1** (previously 18.20.2). Upgrade your runtime — along with any CI, Docker images, and deployment targets — to the latest node LTS version or newer before upgrading to 4.0.
|
|
1258
|
+
|
|
1259
|
+
### Minimum supported Next.js version is now 16.4.1 ([#16537](https://github.com/payloadcms/payload/pull/16537))
|
|
1260
|
+
|
|
1261
|
+
Older versions of Next.js are no longer supported. Update Next.js to **16.4.1** or newer within the `16.x` release line.
|
|
1262
|
+
|
|
1263
|
+
React and React DOM must satisfy `^19.3.1`. TanStack Start applications also require `@vitejs/plugin-rsc` `^0.5.38`. These minimums include the fixes for [GHSA-xqc2-xf4c-x3h3](https://github.com/react/react/security/advisories/GHSA-xqc2-xf4c-x3h3) and its [Next.js advisory](https://github.com/vercel/next.js/security/advisories/GHSA-673q-mjm6-r5xr).
|
|
1035
1264
|
|
|
1036
1265
|
### Minimum supported TypeScript version is now 6.0.3 ([#16692](https://github.com/payloadcms/payload/pull/16692))
|
|
1037
1266
|
|
|
1038
1267
|
Payload's generated types are no longer guaranteed to work on TypeScript versions below **6.0.3** (previously 5.7.3). Upgrade the `typescript` dependency in your project to 6.0.3 or newer.
|
|
1039
1268
|
|
|
1040
|
-
###
|
|
1269
|
+
### The Slate rich text editor has been removed ([#16359](https://github.com/payloadcms/payload/pull/16359))
|
|
1041
1270
|
|
|
1042
1271
|
Starting in Payload 4.0, `@payloadcms/richtext-lexical` is the only supported rich text editor. The `@payloadcms/richtext-slate` package has been deleted and will no longer be published.
|
|
1043
1272
|
|
|
@@ -1052,7 +1281,7 @@ The rich text adapter pattern itself is unchanged — `editor: lexicalEditor({})
|
|
|
1052
1281
|
|
|
1053
1282
|
If you are still using Slate, **do not upgrade to 4.0 yet.** Stay on the latest 3.x release and complete the [Slate → Lexical migration](https://payloadcms.com/docs/rich-text/migration) first.
|
|
1054
1283
|
|
|
1055
|
-
###
|
|
1284
|
+
### Legacy Lexical HTML converters have been removed ([#16548](https://github.com/payloadcms/payload/pull/16548))
|
|
1056
1285
|
|
|
1057
1286
|
The deprecated `HTMLConverterFeature`, `lexicalHTML`, and the per-node `converters.html` API have been removed from `@payloadcms/richtext-lexical`. Use `convertLexicalToHTML` and `lexicalHTMLField` from the non-deprecated converter instead.
|
|
1058
1287
|
|
|
@@ -1076,7 +1305,7 @@ The deprecated `HTMLConverterFeature`, `lexicalHTML`, and the per-node `converte
|
|
|
1076
1305
|
|
|
1077
1306
|
Custom nodes that define `converters.html` should export their converters instead.
|
|
1078
1307
|
|
|
1079
|
-
### Lexical
|
|
1308
|
+
### Lexical now uses its built-in HTML element check ([#17104](https://github.com/payloadcms/payload/pull/17104))
|
|
1080
1309
|
|
|
1081
1310
|
The deprecated `isHTMLElement` utility has been removed from `@payloadcms/richtext-lexical`. It was a thin wrapper around `x instanceof HTMLElement` that duplicated a utility already exported by `lexical`. Import it directly from `lexical` instead.
|
|
1082
1311
|
|
|
@@ -1087,9 +1316,9 @@ The deprecated `isHTMLElement` utility has been removed from `@payloadcms/richte
|
|
|
1087
1316
|
|
|
1088
1317
|
`lexical`'s built-in `isHTMLElement` is the canonical implementation and narrows against the node's owning-document `HTMLElement`, so it is also safe across iframes and other realms.
|
|
1089
1318
|
|
|
1090
|
-
### Lexical
|
|
1319
|
+
### Lexical now uses the upstream Markdown package
|
|
1091
1320
|
|
|
1092
|
-
`@payloadcms/richtext-lexical` no longer ships a vendored copy of `@lexical/markdown`. The package is now a direct dependency, every `@lexical/*` package was upgraded from `0.41.0` to `0.
|
|
1321
|
+
`@payloadcms/richtext-lexical` no longer ships a vendored copy of `@lexical/markdown`. The package is now a direct dependency, every `@lexical/*` package was upgraded from `0.41.0` to `0.53.0`, and `@payloadcms/richtext-lexical/lexical/markdown` is a pure passthrough of `@lexical/markdown`.
|
|
1093
1322
|
|
|
1094
1323
|
Most projects use markdown through the editor or through `convertMarkdownToLexical` / `convertLexicalToMarkdown` and need no changes. You are only affected if you import from `@payloadcms/richtext-lexical/lexical/markdown` directly.
|
|
1095
1324
|
|
|
@@ -1113,7 +1342,9 @@ If you keep calling `$convertFromMarkdownString` directly, pass `editorConfig.fe
|
|
|
1113
1342
|
|
|
1114
1343
|
**Whitespace-only markdown table cells now import as an empty paragraph** instead of a text node of padding spaces. This comes from the lexical upgrade, not Payload's own code. No action is required unless you assert on those padding spaces in stored content.
|
|
1115
1344
|
|
|
1116
|
-
|
|
1345
|
+
**Markdown export escapes literal brackets and HTML-like text.** `convertLexicalToMarkdown` now writes text such as `[note]` as `[note]` and `<b>` as `<b>`, so literal text no longer turns into links or HTML when the Markdown is parsed again. Ordinary text such as `AT&T` and `a < b` is unchanged, and `convertMarkdownToLexical` restores the original text. No action is required unless you compare exported Markdown against fixed strings or pass it to a parser that does not decode numeric character references.
|
|
1346
|
+
|
|
1347
|
+
If you import lexical APIs directly through `@payloadcms/richtext-lexical/lexical/*`, also review the [lexical breaking changes](https://github.com/facebook/lexical/releases) between `0.41.0` and `0.53.0`. None of them require action for typical Payload usage.
|
|
1117
1348
|
|
|
1118
1349
|
If your app imports Lexical types or adds custom features, check these changes from `0.50.0`. They also apply to imports through `@payloadcms/richtext-lexical/lexical` and its subpaths:
|
|
1119
1350
|
|
|
@@ -1123,10 +1354,12 @@ If your app imports Lexical types or adds custom features, check these changes f
|
|
|
1123
1354
|
- `SerializedEditorState<T>`, `SerializedElementNode<T>`, and `SerializedRootNode<T>` no longer accept a type argument. Remove `<T>` if you only need the base node type. For a document with your own node types, use Payload's `TypedEditorState<T>` instead. Without a type argument, Lexical's `children` are still typed as `SerializedLexicalNode[]`.
|
|
1124
1355
|
- `ReturnType<Node['exportJSON']>` can now infer partial JSON, making fields such as `version` and `url` optional. If your code expects the full format, use the node's explicit serialized type, such as `SerializedLinkNode`. A normal `node.exportJSON()` call still returns the full format.
|
|
1125
1356
|
- `LexicalNode.getCommonAncestor` was removed. Use `$getCommonAncestor(a, b)?.commonAncestor ?? null`; pass the parents of non-element nodes if you need the old method's behavior.
|
|
1357
|
+
- Node traversal and key lookup methods no longer accept a type argument: `getParent<T>()`, `getParentOrThrow<T>()`, `getChildren<T>()`, `getFirstChild<T>()`, `getNextSibling<T>()`, `$getNodeByKey<T>()` and the rest of that family. Remove `<T>` and narrow the result with a node guard, for example `node.getChildren().filter($isTableCellNode)`. Runtime behavior is unchanged.
|
|
1358
|
+
- The deprecated `LinkImportExtension`, `ListImportExtension` and `RichTextImportExtension` were removed. Use `LinkExtension`, `ListExtension` and `RichTextExtension` instead. `HorizontalRuleImportExtension` was also removed; use `HorizontalRuleExtension` from `@lexical/extension` together with an extension that includes `CoreImportExtension`. The `*ImportRules` arrays remain.
|
|
1126
1359
|
|
|
1127
|
-
### Lexical
|
|
1360
|
+
### Lexical table support is no longer experimental
|
|
1128
1361
|
|
|
1129
|
-
|
|
1362
|
+
`EXPERIMENTAL_TableFeature` has been renamed to `TableFeature` now that the table feature is no longer experimental.
|
|
1130
1363
|
|
|
1131
1364
|
```diff
|
|
1132
1365
|
- import { EXPERIMENTAL_TableFeature } from '@payloadcms/richtext-lexical'
|
|
@@ -1140,7 +1373,45 @@ The table feature is no longer experimental, so it drops its prefix.
|
|
|
1140
1373
|
|
|
1141
1374
|
Stored content is unaffected.
|
|
1142
1375
|
|
|
1143
|
-
###
|
|
1376
|
+
### Lexical: `LexicalEditorProps` renamed to `LexicalEditorArgs`
|
|
1377
|
+
|
|
1378
|
+
The `LexicalEditorProps` type exported from `@payloadcms/richtext-lexical` has been renamed to `LexicalEditorArgs`. It describes the arguments of the `lexicalEditor` function, not component props. The shape is unchanged.
|
|
1379
|
+
|
|
1380
|
+
```diff
|
|
1381
|
+
- import type { LexicalEditorProps } from '@payloadcms/richtext-lexical'
|
|
1382
|
+
+ import type { LexicalEditorArgs } from '@payloadcms/richtext-lexical'
|
|
1383
|
+
```
|
|
1384
|
+
|
|
1385
|
+
### Lexical: `UploadDataImproved` replaced by `UploadData` ([#18606](https://github.com/payloadcms/payload/pull/18606))
|
|
1386
|
+
|
|
1387
|
+
The internal `UploadDataImproved` type has been removed, and its definition is now used by the public `UploadData` type. Replace any `UploadDataImproved` imports and type references with `UploadData`:
|
|
1388
|
+
|
|
1389
|
+
```ts
|
|
1390
|
+
import type { UploadData } from '@payloadcms/richtext-lexical'
|
|
1391
|
+
```
|
|
1392
|
+
|
|
1393
|
+
### Lexical: the `version` of nodes is ignored
|
|
1394
|
+
|
|
1395
|
+
Lexical deprecated the `version` property of serialized nodes, and now ignores it when it loads a document. Payload no longer reads it either.
|
|
1396
|
+
|
|
1397
|
+
**Rich text written by the Payload 3.0 betas is no longer upgraded when it's loaded.** Payload used `version: 1` to detect two older shapes:
|
|
1398
|
+
|
|
1399
|
+
- Block nodes whose fields were wrapped in an extra `data` object (`fields.data`)
|
|
1400
|
+
- Relationship and upload nodes that stored the whole related document in `value`, instead of its ID
|
|
1401
|
+
|
|
1402
|
+
If your database may still contain rich text from the 3.0 betas, run `upgradeLexicalData` on the latest 3.x release before you upgrade to 4.0. It re-saves every document, which converts these shapes:
|
|
1403
|
+
|
|
1404
|
+
```ts
|
|
1405
|
+
import { upgradeLexicalData } from '@payloadcms/richtext-lexical'
|
|
1406
|
+
|
|
1407
|
+
await upgradeLexicalData({ payload })
|
|
1408
|
+
```
|
|
1409
|
+
|
|
1410
|
+
**`version` is optional in the JSON schema of Lexical nodes.** The CLI and MCP no longer require it, and leave it out of the schema they show agents. They still accept it, so existing documents, which contain `version`, stay valid input.
|
|
1411
|
+
|
|
1412
|
+
**Payload doesn't add or remove `version` when it saves rich text.** Rich text created by Lexical, like in the admin panel, still has `version: 1` on every node, because Lexical's JSON export writes it. Payload's own nodes used to write their own numbers instead (like `2` for blocks), and now write `1` as well. Rich text sent through the API, CLI or MCP is saved as sent, so it may not contain `version`. The generated types still include `version`, marked as deprecated, so don't rely on it being there.
|
|
1413
|
+
|
|
1414
|
+
### Field schema configuration now reflects JSON Schema
|
|
1144
1415
|
|
|
1145
1416
|
`typescriptSchema` accepted JSON Schema, not TypeScript, so the name lied. Renamed to `jsonSchema`. Same shape, same array of transforms. The underlying schema is now also consumed by the MCP plugin for runtime validation, not just type generation.
|
|
1146
1417
|
|
|
@@ -1153,9 +1424,9 @@ Stored content is unaffected.
|
|
|
1153
1424
|
}
|
|
1154
1425
|
```
|
|
1155
1426
|
|
|
1156
|
-
###
|
|
1427
|
+
### Rich text output schemas have been renamed
|
|
1157
1428
|
|
|
1158
|
-
|
|
1429
|
+
The Rich Text adapter's `outputSchema` property has been renamed to `jsonSchema`. The arguments object also gains `typeStringDefinitions: Set<string>` — a sink for raw TS source appended to `payload-types.ts`.
|
|
1159
1430
|
|
|
1160
1431
|
```diff
|
|
1161
1432
|
myAdapter: RichTextAdapter = {
|
|
@@ -1168,7 +1439,7 @@ Same story on the editor side. The arguments object also gains `typeStringDefini
|
|
|
1168
1439
|
|
|
1169
1440
|
`@payloadcms/richtext-lexical` is updated. Only third-party adapters need attention.
|
|
1170
1441
|
|
|
1171
|
-
###
|
|
1442
|
+
### Schema generation now returns definitions alongside JSON Schema
|
|
1172
1443
|
|
|
1173
1444
|
`configToJSONSchema` (from `payload`) used to return a `JSONSchema4` directly. It now returns an object with the schema plus the TS-source sink. Destructure to pull the schema out.
|
|
1174
1445
|
|
|
@@ -1179,7 +1450,7 @@ Same story on the editor side. The arguments object also gains `typeStringDefini
|
|
|
1179
1450
|
|
|
1180
1451
|
If you run your own type generation, append `[...typeStringDefinitions].join('\n\n')` to the compiled output. Otherwise ignore it.
|
|
1181
1452
|
|
|
1182
|
-
###
|
|
1453
|
+
### Field schema generation now uses object arguments
|
|
1183
1454
|
|
|
1184
1455
|
`fieldsToJSONSchema` used to take 6 positional arguments. It now takes one object. The new shape also requires `typeStringDefinitions`, and `forceInlineBlocks` is a top-level sibling instead of nested under `opts`.
|
|
1185
1456
|
|
|
@@ -1203,9 +1474,9 @@ If you run your own type generation, append `[...typeStringDefinitions].join('\n
|
|
|
1203
1474
|
+ })
|
|
1204
1475
|
```
|
|
1205
1476
|
|
|
1206
|
-
###
|
|
1477
|
+
### Entity schema generation now requires type definitions
|
|
1207
1478
|
|
|
1208
|
-
|
|
1479
|
+
`entityToJSONSchema` now requires a `typeStringDefinitions` argument at position 5, between `defaultIDType` and `collectionIDFieldTypes`. The old `opts: ConfigToJSONSchemaOptions` is replaced by an optional positional `forceInlineBlocks?: boolean` at the end.
|
|
1209
1480
|
|
|
1210
1481
|
```diff
|
|
1211
1482
|
entityToJSONSchema(
|
|
@@ -1221,7 +1492,7 @@ Inserted at position 5 (between `defaultIDType` and `collectionIDFieldTypes`). T
|
|
|
1221
1492
|
)
|
|
1222
1493
|
```
|
|
1223
1494
|
|
|
1224
|
-
### Lexical
|
|
1495
|
+
### Lexical nodes now provide their own JSON Schemas
|
|
1225
1496
|
|
|
1226
1497
|
`generatedTypes.modifyJSONSchema` on lexical features (and the sanitized `modifyJSONSchemas` array) is removed. Features now contribute per-node JSON Schemas via `createNode({ jsonSchema, node })` instead of mutating a whole-field schema after the fact. The editor composes per-node schemas into the field's union automatically.
|
|
1227
1498
|
|
|
@@ -1277,7 +1548,7 @@ The same rule applies to lexical block nodes — they now emit as `SerializedBlo
|
|
|
1277
1548
|
|
|
1278
1549
|
When two **different** blocks resolve to the same auto-derived name (same slug, different fields — e.g. a shared block overridden in one collection), the first keeps the clean name and any later block with a different shape gets a stable content-hash suffix (`Hero_3F2A1B0C`), so neither is silently mistyped. To choose the name yourself — or to resolve a collision with another type in your generated file (a collection, an array's `interfaceName`, etc.) — set an explicit `interfaceName` on the block. See [Block interface name collisions](/docs/typescript/generating-types#block-interface-name-collisions).
|
|
1279
1550
|
|
|
1280
|
-
###
|
|
1551
|
+
### Block references now share the blocks array
|
|
1281
1552
|
|
|
1282
1553
|
The `blockReferences` property on blocks fields has been removed. The `blocks` property now accepts both inline block configs and string slugs for blocks defined in the top-level Payload Config `blocks` array.
|
|
1283
1554
|
|
|
@@ -1308,7 +1579,7 @@ Inline blocks continue to work as before:
|
|
|
1308
1579
|
}
|
|
1309
1580
|
```
|
|
1310
1581
|
|
|
1311
|
-
### Lexical
|
|
1582
|
+
### Generated Lexical types are now strict
|
|
1312
1583
|
|
|
1313
1584
|
`richText` fields backed by `lexicalEditor` used to emit a permissive `{ [k: string]: unknown }` per field. They now emit a discriminated union of strict per-node interfaces (`SerializedTextNode`, `SerializedParagraphNode`, `SerializedHeadingNode`, `SerializedBlockNode`, etc.) under a hash-named alias like `LexicalNodes_AB12CD34`.
|
|
1314
1585
|
|
|
@@ -1339,7 +1610,7 @@ Element nodes are now generic over their `children`, and you pass the node union
|
|
|
1339
1610
|
|
|
1340
1611
|
`SerializedTextNode` is a leaf, so it stays bare. For the built-in nodes plus a few of your own, `WithDefaultNodes` threads the union for you - pass your custom node(s) as the generic (`type MyNodes = WithDefaultNodes<SerializedBlockNode<MyBlockData>>`), and they're usable anywhere a node can appear, not just at the top level. `DefaultTypedEditorState` with only built-in nodes needs no change.
|
|
1341
1612
|
|
|
1342
|
-
### Generated JSON Schema uses
|
|
1613
|
+
### Generated JSON Schema now uses modern definitions
|
|
1343
1614
|
|
|
1344
1615
|
Payload builds a JSON Schema from your config to generate `payload-types.ts`. That schema now stores its reusable types under the modern `$defs` key instead of the older `definitions` key, and every internal reference points at `#/$defs/...` instead of `#/definitions/...`. This follows the current JSON Schema spec.
|
|
1345
1616
|
|
|
@@ -1397,7 +1668,7 @@ jobs: {
|
|
|
1397
1668
|
|
|
1398
1669
|
Job documents can contain inputs, outputs, logs, and execution state, so avoid enabling write access unless your application specifically requires it.
|
|
1399
1670
|
|
|
1400
|
-
###
|
|
1671
|
+
### Job queries and hooks now have fixed behavior ([#16414](https://github.com/payloadcms/payload/pull/16414))
|
|
1401
1672
|
|
|
1402
1673
|
The deprecated `jobs.depth` and `jobs.runHooks` config options have been removed. Job operations now always use direct database calls with depth `0`.
|
|
1403
1674
|
|
|
@@ -1405,7 +1676,7 @@ If you relied on either option, remove it from your `jobs` config. If you depend
|
|
|
1405
1676
|
|
|
1406
1677
|
The `jobsCollectionOverrides` warning that detected extra hooks and prompted users to set `runHooks` has also been removed.
|
|
1407
1678
|
|
|
1408
|
-
###
|
|
1679
|
+
### The legacy base job type has been removed
|
|
1409
1680
|
|
|
1410
1681
|
The deprecated `BaseJob` type is no longer exported. Use `Job` everywhere you previously used `BaseJob`.
|
|
1411
1682
|
|
|
@@ -1463,9 +1734,9 @@ The deprecated `RunningJob` and `RunningJobSimple` types have also been removed.
|
|
|
1463
1734
|
|
|
1464
1735
|
JSON workflow steps without a `task` must now provide an `inlineTask` handler. This removes a type escape that previously allowed an incomplete step even though it could not run.
|
|
1465
1736
|
|
|
1466
|
-
###
|
|
1737
|
+
### Custom database adapters must support job claiming
|
|
1467
1738
|
|
|
1468
|
-
|
|
1739
|
+
Custom database adapters must now implement `updateJobs` so Payload can use a unique `processingToken` when claiming jobs and prevent multiple workers from running the same job. This adds an internal, nullable `processingToken` field to the `payload-jobs` collection. Existing SQL databases need a migration that adds this column. MongoDB does not require a migration.
|
|
1469
1740
|
|
|
1470
1741
|
The default `updateJobs` implementation has been removed because it could not safely claim jobs across multiple workers. If you maintain a custom database adapter, you must now provide `updateJobs`. It must only claim jobs that still match the provided `where` condition and, when a `processingToken` is provided, return only the jobs claimed with that token. The official Payload database adapters already implement this behavior.
|
|
1471
1742
|
|
|
@@ -1477,7 +1748,7 @@ Worker updates use a 30-second safety buffer by default, so an update only start
|
|
|
1477
1748
|
|
|
1478
1749
|
Existing SQL databases need a migration that replaces `processing` with the nullable, indexed `processingUntil` column. MongoDB does not require a migration.
|
|
1479
1750
|
|
|
1480
|
-
###
|
|
1751
|
+
### Job task results no longer include state ([#16416](https://github.com/payloadcms/payload/pull/16416))
|
|
1481
1752
|
|
|
1482
1753
|
Job task handlers and `inlineTask` callbacks can no longer use the `state` field to signal success or failure. Both shapes were deprecated in v3 and are now removed from tasks and inline tasks.
|
|
1483
1754
|
|
|
@@ -1502,7 +1773,7 @@ const myTask: TaskHandler<'MyTask'> = async ({ input }) => {
|
|
|
1502
1773
|
}
|
|
1503
1774
|
```
|
|
1504
1775
|
|
|
1505
|
-
###
|
|
1776
|
+
### Cron expressions now require explicit ranges ([#16546](https://github.com/payloadcms/payload/pull/16546))
|
|
1506
1777
|
|
|
1507
1778
|
The `sloppyRanges: true` setting that kept Croner v9 stepping syntax working after the v10 upgrade has been removed. Croner now enforces stricter cron parsing rules, so stepping expressions must use either `*` or an explicit range before the `/`.
|
|
1508
1779
|
|
|
@@ -1534,7 +1805,7 @@ Migrate any affected cron expressions:
|
|
|
1534
1805
|
+ cron: '30 * * * *'
|
|
1535
1806
|
```
|
|
1536
1807
|
|
|
1537
|
-
###
|
|
1808
|
+
### Relationship and upload limits now use row-based options ([#16547](https://github.com/payloadcms/payload/pull/16547))
|
|
1538
1809
|
|
|
1539
1810
|
The deprecated `min` and `max` properties have been removed from `relationship` and `upload` fields with `hasMany: true`. Use `minRows` and `maxRows` instead.
|
|
1540
1811
|
|
|
@@ -1553,7 +1824,7 @@ The deprecated `min` and `max` properties have been removed from `relationship`
|
|
|
1553
1824
|
|
|
1554
1825
|
The same change applies to `upload` fields with `hasMany: true`.
|
|
1555
1826
|
|
|
1556
|
-
###
|
|
1827
|
+
### Nested localized fields no longer need a compatibility flag ([#16693](https://github.com/payloadcms/payload/pull/16693))
|
|
1557
1828
|
|
|
1558
1829
|
`config.compatibility.allowLocalizedWithinLocalized` and the `PAYLOAD_DO_NOT_SANITIZE_LOCALIZED_PROPERTY` environment variable have been removed. Sanitize no longer strips `localized: true` from fields nested under a localized parent — `fieldShouldBeLocalized` decides this at runtime instead.
|
|
1559
1830
|
|
|
@@ -1567,7 +1838,7 @@ The same change applies to `upload` fields with `hasMany: true`.
|
|
|
1567
1838
|
- Remove the `compatibility` block from your config. If your MongoDB data still has the redundant nested-localized shape, flatten the config and run a data migration.
|
|
1568
1839
|
- Replace any direct `field.localized` reads in custom code with `fieldShouldBeLocalized({ field, parentIsLocalized })` from `payload/shared`.
|
|
1569
1840
|
|
|
1570
|
-
###
|
|
1841
|
+
### Publishing now defaults to the active locale
|
|
1571
1842
|
|
|
1572
1843
|
The Admin UI Publish button now always defaults to publishing only the active locale when a collection or global has localized fields and you have publish permission. "Publish all locales" is available as a secondary option in the Publish button's dropdown. This previously required opting in via `localization.defaultLocalePublishOption: 'active'`; the config option has been removed since active-locale-only is now the permanent default.
|
|
1573
1844
|
|
|
@@ -1589,7 +1860,7 @@ export default buildConfig({
|
|
|
1589
1860
|
|
|
1590
1861
|
Run `npx @payloadcms/codemod --transform remove-default-locale-publish-option` to remove the property automatically. The codemod surfaces a note for any config that had it set to `'all'`, since that combination previously changed the default and now has no config equivalent.
|
|
1591
1862
|
|
|
1592
|
-
### Storage adapters
|
|
1863
|
+
### Storage adapters have moved to top-level configuration ([#16596](https://github.com/payloadcms/payload/pull/16596))
|
|
1593
1864
|
|
|
1594
1865
|
Storage adapter packages (`@payloadcms/storage-s3`, `-azure`, `-gcs`, `-r2`, `-vercel-blob`) must now be placed under the top-level `storage` key in your Payload config instead of inside `plugins`.
|
|
1595
1866
|
|
|
@@ -1677,8 +1948,19 @@ If you typed `clientUploads.access`, replace `ClientUploadsAccess` with `UploadI
|
|
|
1677
1948
|
|
|
1678
1949
|
#### If you maintain a custom storage adapter
|
|
1679
1950
|
|
|
1951
|
+
File versioning adds a required `GeneratedAdapter.copyFile` method. Copy `from` to `to` (complete storage keys) without changing the source, reject an existing destination, and return only once the destination is readable. `moveFile` stays optional. See [Custom Storage Adapters](../upload/storage-adapters) for the full contract.
|
|
1952
|
+
|
|
1680
1953
|
Replace `clientUploadContext` with `uploadReference` in generated file metadata and static handler parameters. `handleUpload` no longer receives it because Payload skips uploading files that are already stored.
|
|
1681
1954
|
|
|
1955
|
+
Payload keeps only `_objectKey`, `prefix`, and `signedReceipt` at the top level of `uploadReference`, plus signed `adapterData` when `requiresUploadReceipt` is set. Read any other field your adapter or client added from `uploadReference.clientData`:
|
|
1956
|
+
|
|
1957
|
+
```diff
|
|
1958
|
+
- const objectID = uploadReference.providerObjectID
|
|
1959
|
+
+ const objectID = uploadReference.clientData?.providerObjectID
|
|
1960
|
+
```
|
|
1961
|
+
|
|
1962
|
+
`clientData` is not verified. To trust a value, sign it into the upload receipt as `adapterData` instead. See [Upload receipts](../upload/storage-adapters#custom-upload-receipts).
|
|
1963
|
+
|
|
1682
1964
|
Set `uploadInstructions.enabled`. When false, Payload adds `adminHandler` to the import map without rendering it. When true, Payload also renders it and exposes the instructions and supporting endpoint.
|
|
1683
1965
|
|
|
1684
1966
|
Move access checks into the generator or supporting endpoint that authorizes the upload:
|
|
@@ -1759,7 +2041,7 @@ uploadInstructions: {
|
|
|
1759
2041
|
|
|
1760
2042
|
Both are optional. Custom handler props are now passed as `props`, and the supporting route is available as `endpointPath` instead of `serverHandlerPath`. The old Admin component `enabled` prop was removed.
|
|
1761
2043
|
|
|
1762
|
-
###
|
|
2044
|
+
### The Uploadthing storage adapter has been removed
|
|
1763
2045
|
|
|
1764
2046
|
The Uploadthing storage adapter, deprecated in a previous release, has been deleted and will no longer be published. Migrate to another storage adapter such as `@payloadcms/storage-s3` before upgrading to 4.0.
|
|
1765
2047
|
|
|
@@ -1814,7 +2096,7 @@ azureStorage({
|
|
|
1814
2096
|
|
|
1815
2097
|
Run `npx @payloadcms/codemod --transform migrate-azure-chunk-large-files` to remove the flag automatically (it collapses `clientUploads: { chunkLargeFiles: true }` to `clientUploads: true` and keeps any other `clientUploads` options).
|
|
1816
2098
|
|
|
1817
|
-
### Sharp
|
|
2099
|
+
### Sharp is now an optional file transformer #sharp-moved-out-of-core-into-payloadcmstransformer-sharp
|
|
1818
2100
|
|
|
1819
2101
|
Image resizing is no longer built into `payload` itself. It now ships as an official [file transformer](../upload/transformers), `@payloadcms/transformer-sharp`, that you register under `upload.transformers`.
|
|
1820
2102
|
|
|
@@ -1874,7 +2156,7 @@ If you inject a custom Sharp build or version, pass it the same way:
|
|
|
1874
2156
|
|
|
1875
2157
|
`sharpTransformer` can also resize images at request time (`/api/media/file/photo.png?width=400`). This is new in Payload 4 and **disabled by default**, so a migrated config keeps serving only the original file and your pre-generated `variants`. The codemod doesn't enable it. To opt in, pass `dynamic: true` or `dynamic: { collections: ['media'] }` — see [Dynamic (request-time) resizing](../upload/transformers#dynamic-request-time-resizing), and [Securing dynamic resizing](../upload/transformers#securing-dynamic-resizing) before enabling it on a publicly readable collection.
|
|
1876
2158
|
|
|
1877
|
-
####
|
|
2159
|
+
#### Upload image data now uses variants
|
|
1878
2160
|
|
|
1879
2161
|
The group field that holds each generated image size on an upload document is now `variants` instead of `sizes`. Every place that reads or queries it changes:
|
|
1880
2162
|
|
|
@@ -1934,7 +2216,7 @@ Registering any transformer under `upload.transformers` — including `sharpTran
|
|
|
1934
2216
|
|
|
1935
2217
|
To link to a file from your own code, including with transformer query parameters, use the new `generatePayloadFileURL` helper (exported from `payload` and `payload/shared`). It always builds the access-controlled Payload file endpoint, so links never bypass `access.read` by pointing straight at storage.
|
|
1936
2218
|
|
|
1937
|
-
### Storage
|
|
2219
|
+
### Storage prefixes are now always included
|
|
1938
2220
|
|
|
1939
2221
|
The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` adapter: `-s3`, `-azure`, `-gcs`, `-r2`, `-vercel-blob`) has been removed. The behavior it used to opt into — always inserting the hidden `prefix` field into the collection schema — is now unconditional, so the schema stays consistent whether or not a collection configures a `prefix` and whether or not the plugin is `enabled`.
|
|
1940
2222
|
|
|
@@ -1949,7 +2231,29 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
|
|
|
1949
2231
|
- Remove `alwaysInsertFields` from your storage adapter or `cloudStoragePlugin` config — it has no effect and no longer exists on the option types.
|
|
1950
2232
|
- For Postgres, SQLite, or D1 projects, run `payload migrate:create` to generate the migration that adds the `prefix` column, then run `payload migrate` to apply it.
|
|
1951
2233
|
|
|
1952
|
-
###
|
|
2234
|
+
### Upload collections retain originals and file history
|
|
2235
|
+
|
|
2236
|
+
Upload collections now store `original` metadata and a `prefix` and `_objectKey` for each stored file (the main file, `original`, and each variant), so saved versions can find their files. New uploads keep their uploaded filename. With a storage adapter, each new file is stored under its own `_objectKey` folder, so update any code or infrastructure that relies on the old object key. When a processed main file and its original share a filename, request the original with `?original=true`; `original.url` already includes it. With local storage, the original gets a counter name instead (for example `photo-1.png`). Files saved by earlier v4 beta releases with an `-original` filename keep that name and are still served. Custom storage adapters should handle the new `params.isOriginal` in `staticHandler`; see [Custom Storage Adapters](../upload/storage-adapters#custom-storage-adapters).
|
|
2237
|
+
|
|
2238
|
+
**Postgres and SQLite:** after updating, run `payload migrate:create`, check that it adds these columns to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` values until their next write.
|
|
2239
|
+
|
|
2240
|
+
### Upload collections save crop and focal point edits in `_transforms`
|
|
2241
|
+
|
|
2242
|
+
Upload collections now have a `_transforms` JSON field that saves the crop and focal point, so an edit can start again from the retained original. See [Saved crop and focal point](../upload/overview#saved-crop-and-focal-point).
|
|
2243
|
+
|
|
2244
|
+
- `_transforms` is a reserved field name on upload collections. If an upload collection defines its own field named `_transforms`, rename it and move its data before you update.
|
|
2245
|
+
- `focalX` and `focalY` stay available and match `_transforms.focalPoint` when it is set. For a document saved before `_transforms` existed, the first write that saves `_transforms` copies its focal point into `_transforms`.
|
|
2246
|
+
- Replacing the file now sets `focalX` and `focalY` to the center, unless the request sends a new focal point. Before, the old values stayed on the document, but the new image sizes did not use them.
|
|
2247
|
+
|
|
2248
|
+
**Postgres and SQLite:** run `payload migrate:create`, check that it adds a `_transforms` column to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` until their next write.
|
|
2249
|
+
|
|
2250
|
+
Upload collections also have a core-controlled `_stored` field on the main file, on `original`, and on each entry under `variants`. A value of `false` marks an entry with no stored object. A missing or `null` value means stored, so existing documents need no data backfill. Payload ignores client writes to this field. It is hidden in the Admin Panel, but can appear in API responses; it is not a field-level hidden value. See [Files with no stored default](../upload/transformers#files-with-no-stored-default).
|
|
2251
|
+
|
|
2252
|
+
`_stored` is now reserved for these file entries. If an upload collection already defines a custom `_stored` field, rename it and move its data, including data in saved versions, before upgrading. Remove the old custom values from `_stored`: existing `false` values would otherwise be treated as files with no stored object, and writes to the custom field would be ignored.
|
|
2253
|
+
|
|
2254
|
+
**Postgres and SQLite:** run `payload migrate:create`, check that it adds the `_stored` columns for file entries in each upload collection and its versions, then run `payload migrate`. Existing rows keep `null`.
|
|
2255
|
+
|
|
2256
|
+
### File size types have been consolidated ([#16593](https://github.com/payloadcms/payload/pull/16593))
|
|
1953
2257
|
|
|
1954
2258
|
`FileSizeImproved` has been merged into `FileSize`. The `url`, `width`, `height`, `filesize`, `mimeType`, and `filename` properties now accept `null` directly on `FileSize`, matching what the database stores for sizes that were not generated.
|
|
1955
2259
|
|
|
@@ -1958,9 +2262,9 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
|
|
|
1958
2262
|
+ import type { FileSize } from 'payload'
|
|
1959
2263
|
```
|
|
1960
2264
|
|
|
1961
|
-
###
|
|
2265
|
+
### Image size admin controls have been consolidated ([#16593](https://github.com/payloadcms/payload/pull/16593))
|
|
1962
2266
|
|
|
1963
|
-
The
|
|
2267
|
+
The `disableListColumn`, `disableListFilter`, and `disableGroupBy` properties under `ImageSize.admin` have been replaced with a single `disabled` object, consistent with the shape used by all other fields.
|
|
1964
2268
|
|
|
1965
2269
|
```diff
|
|
1966
2270
|
{
|
|
@@ -1977,7 +2281,7 @@ The three individual boolean props have been replaced with a single `disabled` o
|
|
|
1977
2281
|
|
|
1978
2282
|
Run `npx @payloadcms/codemod --transform migrate-disabled-fields` to migrate automatically.
|
|
1979
2283
|
|
|
1980
|
-
###
|
|
2284
|
+
### MongoDB queries no longer use facet aggregation ([#16612](https://github.com/payloadcms/payload/pull/16612))
|
|
1981
2285
|
|
|
1982
2286
|
The `useFacet` option in `mongooseAdapter` config has been removed. Payload no longer uses `$facet` aggregation, so the option has no effect.
|
|
1983
2287
|
|
|
@@ -1989,7 +2293,7 @@ The `useFacet` option in `mongooseAdapter` config has been removed. Payload no l
|
|
|
1989
2293
|
})
|
|
1990
2294
|
```
|
|
1991
2295
|
|
|
1992
|
-
###
|
|
2296
|
+
### Search plugin API paths are now derived automatically ([#16597](https://github.com/payloadcms/payload/pull/16597))
|
|
1993
2297
|
|
|
1994
2298
|
The deprecated `apiBasePath` option on the search plugin has been removed. The plugin now derives the correct path from the root config automatically.
|
|
1995
2299
|
|
|
@@ -2001,7 +2305,7 @@ The sha1 HMAC fallback for API key authentication has been removed. API keys are
|
|
|
2001
2305
|
|
|
2002
2306
|
**How to migrate:** Open the user document for each affected API key holder and save it — this regenerates the key under sha256. Alternatively, generate a new API key from the admin panel.
|
|
2003
2307
|
|
|
2004
|
-
###
|
|
2308
|
+
### API key fields now use a factory
|
|
2005
2309
|
|
|
2006
2310
|
The `baseAPIKeyFields` export from `payload` has been removed. Use `createAPIKeyFields()` instead. It returns the same default auth API key storage fields, and also accepts overrides for projects or plugins that need to customize the generated field configs.
|
|
2007
2311
|
|
|
@@ -2030,9 +2334,9 @@ createAPIKeyFields({
|
|
|
2030
2334
|
})
|
|
2031
2335
|
```
|
|
2032
2336
|
|
|
2033
|
-
###
|
|
2337
|
+
### MCP plugin configuration and authentication have changed
|
|
2034
2338
|
|
|
2035
|
-
|
|
2339
|
+
`@payloadcms/plugin-mcp` has a new public config API, built-in tool inputs, and API-key authentication flow. Update your plugin config and recreate MCP credentials as user API keys.
|
|
2036
2340
|
|
|
2037
2341
|
**Collections and globals are now opt-out.** Drop the `enabled` flag. Every collection and global is exposed by default through the generic built-in tools. For collections, this includes tools like `getCollectionSchema`, `findDocuments`, `countDocuments`, `createDocuments`, `updateDocument`, `deleteDocuments`, `duplicateDocument`, and `findDistinct`, plus version tools when versions are enabled. For globals, this includes `getGlobalSchema`, `findGlobal`, and `updateGlobal`, plus version tools when versions are enabled. Turn individual operations off via simple config keys like `tools: { create: false }`.
|
|
2038
2342
|
|
|
@@ -2205,7 +2509,7 @@ By default, MCP items require an authenticated user. Built-in collection and glo
|
|
|
2205
2509
|
|
|
2206
2510
|
**HTTP requests have a size limit.** `POST /api/mcp` now answers request bodies over 4 MiB with `413`. Base64 file uploads count toward this limit. Raise it with `mcp.maxRequestBodySize`.
|
|
2207
2511
|
|
|
2208
|
-
###
|
|
2512
|
+
### Admin UI styles now use CSS and semantic tokens
|
|
2209
2513
|
|
|
2210
2514
|
The Admin UI styles were migrated from SCSS to plain CSS. The `@payloadcms/ui/scss` package export and its SCSS source files have been removed, and the legacy `--theme-*` CSS variables were retired in favor of semantic `--color-*` tokens and the raw `--ramp-*` color palette.
|
|
2211
2515
|
|
|
@@ -2281,7 +2585,7 @@ If you previously used `rest: false`, remove the property; omitting `rest` disab
|
|
|
2281
2585
|
- `hasAPIKey` (3.x virtual field) is removed. Use `apiKeyLast4` and `docPermissions.fields.apiKey`.
|
|
2282
2586
|
- Custom `access.read` on the generated `apiKey` field is inert — reads are hardcoded to deny.
|
|
2283
2587
|
|
|
2284
|
-
###
|
|
2588
|
+
### Uploads now reject oversized files by default
|
|
2285
2589
|
|
|
2286
2590
|
The Payload-wide [`upload.abortOnLimit`](../upload/overview#payload-wide-upload-options) option now defaults to `true`. A file that is bigger than the configured `fileSize` limit now returns an HTTP 413 error by default. Previously, the file was truncated to the limit without any error, and the upload continued.
|
|
2287
2591
|
|
|
@@ -2297,3 +2601,19 @@ export default buildConfig({
|
|
|
2297
2601
|
},
|
|
2298
2602
|
})
|
|
2299
2603
|
```
|
|
2604
|
+
|
|
2605
|
+
### Nodemailer adapter now uses nodemailer 10 ([#18737](https://github.com/payloadcms/payload/pull/18737))
|
|
2606
|
+
|
|
2607
|
+
`@payloadcms/email-nodemailer` now depends on nodemailer 10, which ships its own types. If you pass your own `transport` created with nodemailer 9, it no longer type-checks against the adapter. Upgrade `nodemailer` and remove `@types/nodemailer`:
|
|
2608
|
+
|
|
2609
|
+
```diff
|
|
2610
|
+
"dependencies": {
|
|
2611
|
+
- "nodemailer": "^9.1.1"
|
|
2612
|
+
+ "nodemailer": "^10.1.1"
|
|
2613
|
+
},
|
|
2614
|
+
"devDependencies": {
|
|
2615
|
+
- "@types/nodemailer": "^8.0.0"
|
|
2616
|
+
}
|
|
2617
|
+
```
|
|
2618
|
+
|
|
2619
|
+
If you use `transportOptions`, or pass no config, no changes are needed.
|