@payloadcms/codemod 4.0.0-internal.5e065b3 → 4.0.0-internal.71538a3

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.
Files changed (49) hide show
  1. package/README.md +5 -2
  2. package/dist/registry.d.ts.map +1 -1
  3. package/dist/registry.js +6 -0
  4. package/dist/registry.js.map +1 -1
  5. package/dist/runbook/v4.mdx +311 -76
  6. package/dist/transforms/migrate-admin-context-properties/basic.input.js +32 -0
  7. package/dist/transforms/migrate-admin-context-properties/basic.input.js.map +1 -0
  8. package/dist/transforms/migrate-admin-context-properties/basic.output.js +30 -0
  9. package/dist/transforms/migrate-admin-context-properties/basic.output.js.map +1 -0
  10. package/dist/transforms/migrate-admin-context-properties/index.d.ts +3 -0
  11. package/dist/transforms/migrate-admin-context-properties/index.d.ts.map +1 -0
  12. package/dist/transforms/migrate-admin-context-properties/index.js +302 -0
  13. package/dist/transforms/migrate-admin-context-properties/index.js.map +1 -0
  14. package/dist/transforms/migrate-admin-context-properties/no-match.input.js +30 -0
  15. package/dist/transforms/migrate-admin-context-properties/no-match.input.js.map +1 -0
  16. package/dist/transforms/migrate-admin-context-properties/no-match.output.js +30 -0
  17. package/dist/transforms/migrate-admin-context-properties/no-match.output.js.map +1 -0
  18. package/dist/transforms/migrate-displayed-field-value-args/basic.input.js +4 -0
  19. package/dist/transforms/migrate-displayed-field-value-args/basic.input.js.map +1 -0
  20. package/dist/transforms/migrate-displayed-field-value-args/basic.output.js +8 -0
  21. package/dist/transforms/migrate-displayed-field-value-args/basic.output.js.map +1 -0
  22. package/dist/transforms/migrate-displayed-field-value-args/index.d.ts +3 -0
  23. package/dist/transforms/migrate-displayed-field-value-args/index.d.ts.map +1 -0
  24. package/dist/transforms/migrate-displayed-field-value-args/index.js +84 -0
  25. package/dist/transforms/migrate-displayed-field-value-args/index.js.map +1 -0
  26. package/dist/transforms/migrate-displayed-field-value-args/namespace.input.js +4 -0
  27. package/dist/transforms/migrate-displayed-field-value-args/namespace.input.js.map +1 -0
  28. package/dist/transforms/migrate-displayed-field-value-args/namespace.output.js +8 -0
  29. package/dist/transforms/migrate-displayed-field-value-args/namespace.output.js.map +1 -0
  30. package/dist/transforms/migrate-displayed-field-value-args/no-match.input.js +4 -0
  31. package/dist/transforms/migrate-displayed-field-value-args/no-match.input.js.map +1 -0
  32. package/dist/transforms/migrate-displayed-field-value-args/no-match.output.js +4 -0
  33. package/dist/transforms/migrate-displayed-field-value-args/no-match.output.js.map +1 -0
  34. package/dist/transforms/rename-diff-value-props/basic.input.js +38 -0
  35. package/dist/transforms/rename-diff-value-props/basic.input.js.map +1 -0
  36. package/dist/transforms/rename-diff-value-props/basic.output.js +38 -0
  37. package/dist/transforms/rename-diff-value-props/basic.output.js.map +1 -0
  38. package/dist/transforms/rename-diff-value-props/index.d.ts +3 -0
  39. package/dist/transforms/rename-diff-value-props/index.d.ts.map +1 -0
  40. package/dist/transforms/rename-diff-value-props/index.js +328 -0
  41. package/dist/transforms/rename-diff-value-props/index.js.map +1 -0
  42. package/dist/transforms/rename-diff-value-props/no-match.input.js +8 -0
  43. package/dist/transforms/rename-diff-value-props/no-match.input.js.map +1 -0
  44. package/dist/upgrade/defaultTag.d.ts +1 -1
  45. package/dist/upgrade/defaultTag.js +2 -2
  46. package/dist/upgrade/defaultTag.js.map +1 -1
  47. package/dist/upgrade/prompt.js +3 -3
  48. package/dist/upgrade/prompt.js.map +1 -1
  49. package/package.json +9 -11
@@ -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: 15
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
- ### `overrideAccess` now defaults to `false` on Local API operations
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.
126
150
 
127
- Local API operations whose optional `overrideAccess` value previously defaulted to `true` now default it to `false`, 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.
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.
152
+
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({
@@ -181,7 +209,7 @@ const syncCustomer: CollectionBeforeChangeHook = async ({
181
209
 
182
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.
183
211
 
184
- ### Collection and Global Access Control callbacks receive `slug`
212
+ ### Access Control callbacks now receive document slugs
185
213
 
186
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.
187
215
 
@@ -271,7 +299,7 @@ Payload adds built-in command import references to `cli.commands` while sanitizi
271
299
 
272
300
  See the [Payload CLI documentation](../configuration/cli) for the complete API.
273
301
 
274
- ### `migrateCLI` removed
302
+ ### Legacy migration CLI export removed
275
303
 
276
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.
277
305
 
@@ -300,7 +328,7 @@ The spawned CLI discovers the Payload config from `cwd` or `PAYLOAD_CONFIG_PATH`
300
328
 
301
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.
302
330
 
303
- ### Default query depth reduced to `1`
331
+ ### Default query depth has been reduced
304
332
 
305
333
  Queries that omit `depth` now populate one relationship level instead of two. This reduces database work and response size by default.
306
334
 
@@ -375,7 +403,7 @@ export const Posts: CollectionConfig = {
375
403
  }
376
404
  ```
377
405
 
378
- ### Authorship (`createdBy` / `updatedBy`) is now enabled by default
406
+ ### Authorship is now enabled by default
379
407
 
380
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`.
381
409
 
@@ -414,7 +442,7 @@ The `admin.enableListViewSelectAPI` Collection Config property has been removed.
414
442
 
415
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.
416
444
 
417
- ### Globals: `admin.components.elements` renamed to `admin.components.edit`
445
+ ### Global component slots now match Collections
418
446
 
419
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.
420
448
 
@@ -442,7 +470,7 @@ Globals also now support custom views with arbitrary keys under `admin.component
442
470
 
443
471
  This change is auto-migrated by the `globals-components-edit` codemod.
444
472
 
445
- ### `forceSelect` removed in favor of a `select` function on Collections and Globals
473
+ ### Dynamic selection replaces static forced selection
446
474
 
447
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.
448
476
 
@@ -467,9 +495,9 @@ The same change applies to Globals.
467
495
 
468
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.
469
497
 
470
- #### The `admin.hideAPIURL` property on Collections and Globals has been removed
498
+ #### API tab visibility now uses a condition
471
499
 
472
- 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.
473
501
 
474
502
  ```diff
475
503
  // collections/Posts.ts
@@ -497,7 +525,7 @@ export const PostsCollection: CollectionConfig = {
497
525
 
498
526
  Run `npx @payloadcms/codemod --transform remove-hide-api-url` to migrate automatically.
499
527
 
500
- ### Aliased type and utility re-exports from `@payloadcms/ui` and `@payloadcms/next`
528
+ ### Aliased UI and Next.js re-exports have been removed
501
529
 
502
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.
503
531
 
@@ -583,7 +611,40 @@ To migrate automatically, there's a codemod for this change available by running
583
611
  npx @payloadcms/codemod --transform migrate-field-component-types
584
612
  ```
585
613
 
586
- ### `DefaultValue` function variant is now typed to allow returning a `Promise` ([#17522](https://github.com/payloadcms/payload/pull/17522))
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))
587
648
 
588
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`.
589
650
 
@@ -645,7 +706,7 @@ const interfaceName = global.typescript?.interface
645
706
 
646
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.
647
708
 
648
- ### User types consolidated into `User` and `AuthenticatedUser`
709
+ ### User types have been consolidated
649
710
 
650
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.
651
712
 
@@ -711,7 +772,7 @@ If the field name is dynamic (configurable at runtime), index through `Record<st
711
772
  const value = (user as Record<string, unknown>)[fieldNameFromConfig]
712
773
  ```
713
774
 
714
- ### `multiTenantPlugin` and `searchPlugin` no longer take a type argument
775
+ ### Plugins now infer generated types automatically
715
776
 
716
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`.
717
778
 
@@ -722,9 +783,9 @@ Drop the type argument — your callbacks are typed correctly without it.
722
783
  + multiTenantPlugin({ ... })
723
784
  ```
724
785
 
725
- ### `definePlugin`: `slug` is required and options moved to a named `options` argument
786
+ ### Plugin definitions now require a slug and named options
726
787
 
727
- Two changes to the experimental `definePlugin` helper:
788
+ The experimental `definePlugin` helper now requires a `slug` and passes plugin options through a named `options` argument:
728
789
 
729
790
  - **`slug` is now required.** It registers the plugin in the `plugins` map for cross-plugin discovery. Add one to every `definePlugin` call.
730
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.
@@ -738,9 +799,9 @@ export const myPlugin = definePlugin<MyPluginOptions>({
738
799
  })
739
800
  ```
740
801
 
741
- ### `next/navigation` and `next/link` replaced by framework-agnostic `RouterAdapter` hooks
802
+ ### Admin routing is now framework-agnostic
742
803
 
743
- `@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 (e.g. TanStack Start) without modification.
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.
744
805
 
745
806
  **Hooks** — import from `@payloadcms/ui` instead of `next/navigation`:
746
807
 
@@ -792,7 +853,7 @@ If you were relying on Next-specific extras like `prefetch()` on the router inst
792
853
  />
793
854
  ```
794
855
 
795
- ### `@payloadcms/next/client`, `@payloadcms/next/rsc`, and `@payloadcms/next/templates` removed
856
+ ### Next.js subpath exports have moved to the UI package
796
857
 
797
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.
798
859
 
@@ -830,7 +891,7 @@ If you reference any of these components by string path in your Payload config (
830
891
 
831
892
  Run `npx @payloadcms/codemod --transform migrate-next-subpath-exports` to migrate automatically. It rewrites both `import` declarations and string component paths.
832
893
 
833
- ### `title` and `setDocumentTitle` removed from `useDocumentInfo`
894
+ ### Document title state has moved to its own hook
834
895
 
835
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.
836
897
 
@@ -850,7 +911,7 @@ If you only used `useDocumentInfo` for `title` / `setDocumentTitle`, drop the im
850
911
 
851
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 }`).
852
913
 
853
- ### `useLocale` returns `null` without an active locale
914
+ ### Locale hooks can now return null
854
915
 
855
916
  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.
856
917
 
@@ -880,7 +941,51 @@ When a missing locale is already valid for the receiving API, optional chaining
880
941
  const locale = useLocale()?.code
881
942
  ```
882
943
 
883
- ### RichText adapter `i18n` property removed
944
+ ### `readOnly` removed from the `useField` return type
945
+
946
+ 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.
947
+
948
+ Read `readOnly` from your field component's props instead:
949
+
950
+ ```diff
951
+ 'use client'
952
+ import type { TextFieldClientComponent } from 'payload'
953
+ import { useField } from '@payloadcms/ui'
954
+
955
+ -export const MyField: TextFieldClientComponent = ({ path }) => {
956
+ - const { readOnly, value } = useField({ path })
957
+ +export const MyField: TextFieldClientComponent = ({ path, readOnly }) => {
958
+ + const { value } = useField({ path })
959
+ ```
960
+
961
+ ### Deprecated `TableColumnsProvider` props removed
962
+
963
+ The following deprecated props have been removed from `TableColumnsProvider` and its `TableColumnsProviderProps` type:
964
+
965
+ - `docs`
966
+ - `enableRowSelections`
967
+ - `listPreferences`
968
+ - `preferenceKey`
969
+ - `renderRowTypes`
970
+ - `setTable`
971
+ - `sortColumnProps`
972
+ - `tableAppearance`
973
+
974
+ `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`.
975
+
976
+ ```diff
977
+ <TableColumnsProvider
978
+ collectionSlug={collectionSlug}
979
+ columnState={columnState}
980
+ - enableRowSelections
981
+ - preferenceKey={preferenceKey}
982
+ - tableAppearance="condensed"
983
+ >
984
+ {children}
985
+ </TableColumnsProvider>
986
+ ```
987
+
988
+ ### Rich text adapters no longer expose translations
884
989
 
885
990
  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.
886
991
 
@@ -937,11 +1042,57 @@ export const MyFeature = createServerFeature({
937
1042
 
938
1043
  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.
939
1044
 
940
- ### `transactionIDPromise` removed from `PayloadRequest`
1045
+ ### Transaction requests now use a single identifier property
941
1046
 
942
1047
  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.
943
1048
 
944
- ### Collection `afterOperation` hook: `operation: 'read'` removed
1049
+ ### `headers` and `languageCode` removed from `AdminContext`
1050
+
1051
+ The `headers` and `languageCode` properties have been removed from `AdminContext`, the object returned by `initAdminContext`. Both duplicated values that are already available on `req`:
1052
+
1053
+ ```diff
1054
+ const context = await initAdminContext(args)
1055
+
1056
+ -const userAgent = context.headers.get('user-agent')
1057
+ +const userAgent = context.req.headers.get('user-agent')
1058
+
1059
+ -const languageCode = context.languageCode
1060
+ +const languageCode = context.req.i18n.language
1061
+ ```
1062
+
1063
+ `req.i18n.language` is typed as `string`. Cast it to `AcceptedLanguages` if you need the narrower type.
1064
+
1065
+ `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`.
1066
+
1067
+ #### Codemod
1068
+
1069
+ To migrate automatically, run:
1070
+
1071
+ ```bash
1072
+ npx @payloadcms/codemod --transform migrate-admin-context-properties
1073
+ ```
1074
+
1075
+ 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.
1076
+
1077
+ ### `DiffMethod` type removed
1078
+
1079
+ 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`.
1080
+
1081
+ ### `diffMethod` prop removed from Diff components
1082
+
1083
+ 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.
1084
+
1085
+ Remove `diffMethod` from your props. If you passed it on to a diffing utility, pass `'diffWordsWithSpace'` directly instead:
1086
+
1087
+ ```diff
1088
+ export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
1089
+ - diffMethod,
1090
+ valueFrom,
1091
+ valueTo,
1092
+ }) => {
1093
+ ```
1094
+
1095
+ ### Collection after-operation hooks no longer report read operations
945
1096
 
946
1097
  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.
947
1098
 
@@ -964,14 +1115,14 @@ Run `npx @payloadcms/codemod --transform migrate-after-operation-read` to migrat
964
1115
 
965
1116
  The `operation: 'read'` value on the `beforeOperation` hook is unchanged.
966
1117
 
967
- ### `defaults` config export removed from `payload` ([#17103](https://github.com/payloadcms/payload/pull/17103))
1118
+ ### Static configuration defaults have been removed ([#17103](https://github.com/payloadcms/payload/pull/17103))
968
1119
 
969
- 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.
1120
+ 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.
970
1121
 
971
1122
  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.
972
1123
  Alternatively, you can call `addDefaultsToConfig` to get the unsanitized config but populated with the default properties.
973
1124
 
974
- ### Plugin Import/Export: `toCSV` and `fromCSV` removed
1125
+ ### Import and export field callbacks have moved to hooks
975
1126
 
976
1127
  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.
977
1128
 
@@ -1012,7 +1163,7 @@ The `fromCSV` → `hooks.beforeImport` change is non-breaking for the `data` par
1012
1163
 
1013
1164
  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`.
1014
1165
 
1015
- ### DB Adapter `/types` Subpath Exports Removed
1166
+ ### Database adapter types now use the main package exports
1016
1167
 
1017
1168
  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.
1018
1169
 
@@ -1050,9 +1201,18 @@ If you use a `declare module` augmentation to extend `GeneratedDatabaseSchema` (
1050
1201
 
1051
1202
  Run `npx @payloadcms/codemod --transform migrate-db-types-subpath` to migrate automatically. The codemod handles import declarations, re-export declarations, and `declare module` augmentations.
1052
1203
 
1053
- ### Minimum supported Node.js version is now 24.15.0 ([#16540](https://github.com/payloadcms/payload/pull/16540))
1204
+ ### `findMigrationDir` removed from `@payloadcms/drizzle`
1054
1205
 
1055
- The minimum supported Node.js version is now **24.15.0** (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.
1206
+ The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/drizzle`. Import it from `payload` instead:
1207
+
1208
+ ```diff
1209
+ - import { findMigrationDir } from '@payloadcms/drizzle'
1210
+ + import { findMigrationDir } from 'payload'
1211
+ ```
1212
+
1213
+ ### Minimum supported Node.js version is now 24.22.1 ([#16540](https://github.com/payloadcms/payload/pull/16540))
1214
+
1215
+ 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.
1056
1216
 
1057
1217
  ### Minimum supported Next.js version is now 16.4.0 ([#16537](https://github.com/payloadcms/payload/pull/16537))
1058
1218
 
@@ -1062,7 +1222,7 @@ Older versions of Next.js are no longer supported. Update Next.js to **16.4.0**
1062
1222
 
1063
1223
  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.
1064
1224
 
1065
- ### `@payloadcms/richtext-slate` has been removed ([#16359](https://github.com/payloadcms/payload/pull/16359))
1225
+ ### The Slate rich text editor has been removed ([#16359](https://github.com/payloadcms/payload/pull/16359))
1066
1226
 
1067
1227
  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.
1068
1228
 
@@ -1077,7 +1237,7 @@ The rich text adapter pattern itself is unchanged — `editor: lexicalEditor({})
1077
1237
 
1078
1238
  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.
1079
1239
 
1080
- ### `HTMLConverterFeature` and `lexicalHTML` have been removed ([#16548](https://github.com/payloadcms/payload/pull/16548))
1240
+ ### Legacy Lexical HTML converters have been removed ([#16548](https://github.com/payloadcms/payload/pull/16548))
1081
1241
 
1082
1242
  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.
1083
1243
 
@@ -1101,7 +1261,7 @@ The deprecated `HTMLConverterFeature`, `lexicalHTML`, and the per-node `converte
1101
1261
 
1102
1262
  Custom nodes that define `converters.html` should export their converters instead.
1103
1263
 
1104
- ### Lexical: `isHTMLElement` removed — use lexical's built-in ([#17104](https://github.com/payloadcms/payload/pull/17104))
1264
+ ### Lexical now uses its built-in HTML element check ([#17104](https://github.com/payloadcms/payload/pull/17104))
1105
1265
 
1106
1266
  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.
1107
1267
 
@@ -1112,9 +1272,9 @@ The deprecated `isHTMLElement` utility has been removed from `@payloadcms/richte
1112
1272
 
1113
1273
  `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.
1114
1274
 
1115
- ### Lexical: vendored `@lexical/markdown` fork removed and lexical upgraded to `0.52.0`
1275
+ ### Lexical now uses the upstream Markdown package
1116
1276
 
1117
- `@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.52.0`, and `@payloadcms/richtext-lexical/lexical/markdown` is a pure passthrough of `@lexical/markdown`.
1277
+ `@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`.
1118
1278
 
1119
1279
  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.
1120
1280
 
@@ -1138,7 +1298,9 @@ If you keep calling `$convertFromMarkdownString` directly, pass `editorConfig.fe
1138
1298
 
1139
1299
  **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.
1140
1300
 
1141
- 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.52.0`. None of them require action for typical Payload usage.
1301
+ **Markdown export escapes literal brackets and HTML-like text.** `convertLexicalToMarkdown` now writes text such as `[note]` as `&#91;note&#93;` and `<b>` as `&#60;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.
1302
+
1303
+ 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.
1142
1304
 
1143
1305
  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:
1144
1306
 
@@ -1148,10 +1310,12 @@ If your app imports Lexical types or adds custom features, check these changes f
1148
1310
  - `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[]`.
1149
1311
  - `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.
1150
1312
  - `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.
1313
+ - 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.
1314
+ - 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.
1151
1315
 
1152
- ### Lexical: `EXPERIMENTAL_TableFeature` renamed to `TableFeature`
1316
+ ### Lexical table support is no longer experimental
1153
1317
 
1154
- The table feature is no longer experimental, so it drops its prefix.
1318
+ `EXPERIMENTAL_TableFeature` has been renamed to `TableFeature` now that the table feature is no longer experimental.
1155
1319
 
1156
1320
  ```diff
1157
1321
  - import { EXPERIMENTAL_TableFeature } from '@payloadcms/richtext-lexical'
@@ -1165,7 +1329,45 @@ The table feature is no longer experimental, so it drops its prefix.
1165
1329
 
1166
1330
  Stored content is unaffected.
1167
1331
 
1168
- ### Field `typescriptSchema` renamed to `jsonSchema`
1332
+ ### Lexical: `LexicalEditorProps` renamed to `LexicalEditorArgs`
1333
+
1334
+ 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.
1335
+
1336
+ ```diff
1337
+ - import type { LexicalEditorProps } from '@payloadcms/richtext-lexical'
1338
+ + import type { LexicalEditorArgs } from '@payloadcms/richtext-lexical'
1339
+ ```
1340
+
1341
+ ### Lexical: `UploadDataImproved` replaced by `UploadData` ([#18606](https://github.com/payloadcms/payload/pull/18606))
1342
+
1343
+ 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`:
1344
+
1345
+ ```ts
1346
+ import type { UploadData } from '@payloadcms/richtext-lexical'
1347
+ ```
1348
+
1349
+ ### Lexical: the `version` of nodes is ignored
1350
+
1351
+ Lexical deprecated the `version` property of serialized nodes, and now ignores it when it loads a document. Payload no longer reads it either.
1352
+
1353
+ **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:
1354
+
1355
+ - Block nodes whose fields were wrapped in an extra `data` object (`fields.data`)
1356
+ - Relationship and upload nodes that stored the whole related document in `value`, instead of its ID
1357
+
1358
+ 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:
1359
+
1360
+ ```ts
1361
+ import { upgradeLexicalData } from '@payloadcms/richtext-lexical'
1362
+
1363
+ await upgradeLexicalData({ payload })
1364
+ ```
1365
+
1366
+ **`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.
1367
+
1368
+ **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.
1369
+
1370
+ ### Field schema configuration now reflects JSON Schema
1169
1371
 
1170
1372
  `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.
1171
1373
 
@@ -1178,9 +1380,9 @@ Stored content is unaffected.
1178
1380
  }
1179
1381
  ```
1180
1382
 
1181
- ### RichText adapter `outputSchema` renamed to `jsonSchema`
1383
+ ### Rich text output schemas have been renamed
1182
1384
 
1183
- Same story on the editor side. The arguments object also gains `typeStringDefinitions: Set<string>` — a sink for raw TS source appended to `payload-types.ts`.
1385
+ 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`.
1184
1386
 
1185
1387
  ```diff
1186
1388
  myAdapter: RichTextAdapter = {
@@ -1193,7 +1395,7 @@ Same story on the editor side. The arguments object also gains `typeStringDefini
1193
1395
 
1194
1396
  `@payloadcms/richtext-lexical` is updated. Only third-party adapters need attention.
1195
1397
 
1196
- ### `configToJSONSchema` returns `{ jsonSchema, typeStringDefinitions }`
1398
+ ### Schema generation now returns definitions alongside JSON Schema
1197
1399
 
1198
1400
  `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.
1199
1401
 
@@ -1204,7 +1406,7 @@ Same story on the editor side. The arguments object also gains `typeStringDefini
1204
1406
 
1205
1407
  If you run your own type generation, append `[...typeStringDefinitions].join('\n\n')` to the compiled output. Otherwise ignore it.
1206
1408
 
1207
- ### `fieldsToJSONSchema` switched to object arguments
1409
+ ### Field schema generation now uses object arguments
1208
1410
 
1209
1411
  `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`.
1210
1412
 
@@ -1228,9 +1430,9 @@ If you run your own type generation, append `[...typeStringDefinitions].join('\n
1228
1430
  + })
1229
1431
  ```
1230
1432
 
1231
- ### `entityToJSONSchema` gained a required `typeStringDefinitions` argument
1433
+ ### Entity schema generation now requires type definitions
1232
1434
 
1233
- Inserted at position 5 (between `defaultIDType` and `collectionIDFieldTypes`). The old `opts: ConfigToJSONSchemaOptions` is replaced by an optional positional `forceInlineBlocks?: boolean` at the end.
1435
+ `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.
1234
1436
 
1235
1437
  ```diff
1236
1438
  entityToJSONSchema(
@@ -1246,7 +1448,7 @@ Inserted at position 5 (between `defaultIDType` and `collectionIDFieldTypes`). T
1246
1448
  )
1247
1449
  ```
1248
1450
 
1249
- ### Lexical: `modifyJSONSchema` is gone
1451
+ ### Lexical nodes now provide their own JSON Schemas
1250
1452
 
1251
1453
  `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.
1252
1454
 
@@ -1302,7 +1504,7 @@ The same rule applies to lexical block nodes — they now emit as `SerializedBlo
1302
1504
 
1303
1505
  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).
1304
1506
 
1305
- ### Blocks field `blockReferences` moved into `blocks`
1507
+ ### Block references now share the blocks array
1306
1508
 
1307
1509
  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.
1308
1510
 
@@ -1333,7 +1535,7 @@ Inline blocks continue to work as before:
1333
1535
  }
1334
1536
  ```
1335
1537
 
1336
- ### Lexical: generated `payload-types.ts` shape changed
1538
+ ### Generated Lexical types are now strict
1337
1539
 
1338
1540
  `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`.
1339
1541
 
@@ -1364,7 +1566,7 @@ Element nodes are now generic over their `children`, and you pass the node union
1364
1566
 
1365
1567
  `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.
1366
1568
 
1367
- ### Generated JSON Schema uses `$defs` instead of `definitions`
1569
+ ### Generated JSON Schema now uses modern definitions
1368
1570
 
1369
1571
  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.
1370
1572
 
@@ -1422,7 +1624,7 @@ jobs: {
1422
1624
 
1423
1625
  Job documents can contain inputs, outputs, logs, and execution state, so avoid enabling write access unless your application specifically requires it.
1424
1626
 
1425
- ### Jobs: `jobs.depth` and `jobs.runHooks` have been removed ([#16414](https://github.com/payloadcms/payload/pull/16414))
1627
+ ### Job queries and hooks now have fixed behavior ([#16414](https://github.com/payloadcms/payload/pull/16414))
1426
1628
 
1427
1629
  The deprecated `jobs.depth` and `jobs.runHooks` config options have been removed. Job operations now always use direct database calls with depth `0`.
1428
1630
 
@@ -1430,7 +1632,7 @@ If you relied on either option, remove it from your `jobs` config. If you depend
1430
1632
 
1431
1633
  The `jobsCollectionOverrides` warning that detected extra hooks and prompted users to set `runHooks` has also been removed.
1432
1634
 
1433
- ### Jobs: `BaseJob` has been removed
1635
+ ### The legacy base job type has been removed
1434
1636
 
1435
1637
  The deprecated `BaseJob` type is no longer exported. Use `Job` everywhere you previously used `BaseJob`.
1436
1638
 
@@ -1488,9 +1690,9 @@ The deprecated `RunningJob` and `RunningJobSimple` types have also been removed.
1488
1690
 
1489
1691
  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.
1490
1692
 
1491
- ### Jobs: custom database adapters must implement `updateJobs`
1693
+ ### Custom database adapters must support job claiming
1492
1694
 
1493
- Payload now uses a unique `processingToken` when claiming jobs so multiple workers cannot run 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.
1695
+ 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.
1494
1696
 
1495
1697
  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.
1496
1698
 
@@ -1502,7 +1704,7 @@ Worker updates use a 30-second safety buffer by default, so an update only start
1502
1704
 
1503
1705
  Existing SQL databases need a migration that replaces `processing` with the nullable, indexed `processingUntil` column. MongoDB does not require a migration.
1504
1706
 
1505
- ### Jobs: the `state` field on task return values has been removed ([#16416](https://github.com/payloadcms/payload/pull/16416))
1707
+ ### Job task results no longer include state ([#16416](https://github.com/payloadcms/payload/pull/16416))
1506
1708
 
1507
1709
  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.
1508
1710
 
@@ -1527,7 +1729,7 @@ const myTask: TaskHandler<'MyTask'> = async ({ input }) => {
1527
1729
  }
1528
1730
  ```
1529
1731
 
1530
- ### Croner `sloppyRanges` compatibility setting removed ([#16546](https://github.com/payloadcms/payload/pull/16546))
1732
+ ### Cron expressions now require explicit ranges ([#16546](https://github.com/payloadcms/payload/pull/16546))
1531
1733
 
1532
1734
  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 `/`.
1533
1735
 
@@ -1559,7 +1761,7 @@ Migrate any affected cron expressions:
1559
1761
  + cron: '30 * * * *'
1560
1762
  ```
1561
1763
 
1562
- ### `min` and `max` removed from `relationship` and `upload` fields ([#16547](https://github.com/payloadcms/payload/pull/16547))
1764
+ ### Relationship and upload limits now use row-based options ([#16547](https://github.com/payloadcms/payload/pull/16547))
1563
1765
 
1564
1766
  The deprecated `min` and `max` properties have been removed from `relationship` and `upload` fields with `hasMany: true`. Use `minRows` and `maxRows` instead.
1565
1767
 
@@ -1578,7 +1780,7 @@ The deprecated `min` and `max` properties have been removed from `relationship`
1578
1780
 
1579
1781
  The same change applies to `upload` fields with `hasMany: true`.
1580
1782
 
1581
- ### `allowLocalizedWithinLocalized` compatibility flag removed ([#16693](https://github.com/payloadcms/payload/pull/16693))
1783
+ ### Nested localized fields no longer need a compatibility flag ([#16693](https://github.com/payloadcms/payload/pull/16693))
1582
1784
 
1583
1785
  `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.
1584
1786
 
@@ -1592,7 +1794,7 @@ The same change applies to `upload` fields with `hasMany: true`.
1592
1794
  - 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.
1593
1795
  - Replace any direct `field.localized` reads in custom code with `fieldShouldBeLocalized({ field, parentIsLocalized })` from `payload/shared`.
1594
1796
 
1595
- ### Admin UI Publish button now defaults to the active locale, and `localization.defaultLocalePublishOption` has been removed
1797
+ ### Publishing now defaults to the active locale
1596
1798
 
1597
1799
  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.
1598
1800
 
@@ -1614,7 +1816,7 @@ export default buildConfig({
1614
1816
 
1615
1817
  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.
1616
1818
 
1617
- ### Storage adapters must be declared under `storage`, not `plugins` ([#16596](https://github.com/payloadcms/payload/pull/16596))
1819
+ ### Storage adapters have moved to top-level configuration ([#16596](https://github.com/payloadcms/payload/pull/16596))
1618
1820
 
1619
1821
  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`.
1620
1822
 
@@ -1702,8 +1904,19 @@ If you typed `clientUploads.access`, replace `ClientUploadsAccess` with `UploadI
1702
1904
 
1703
1905
  #### If you maintain a custom storage adapter
1704
1906
 
1907
+ 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.
1908
+
1705
1909
  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.
1706
1910
 
1911
+ 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`:
1912
+
1913
+ ```diff
1914
+ - const objectID = uploadReference.providerObjectID
1915
+ + const objectID = uploadReference.clientData?.providerObjectID
1916
+ ```
1917
+
1918
+ `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).
1919
+
1707
1920
  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.
1708
1921
 
1709
1922
  Move access checks into the generator or supporting endpoint that authorizes the upload:
@@ -1784,7 +1997,7 @@ uploadInstructions: {
1784
1997
 
1785
1998
  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.
1786
1999
 
1787
- ### `@payloadcms/storage-uploadthing` has been removed
2000
+ ### The Uploadthing storage adapter has been removed
1788
2001
 
1789
2002
  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.
1790
2003
 
@@ -1839,7 +2052,7 @@ azureStorage({
1839
2052
 
1840
2053
  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).
1841
2054
 
1842
- ### Sharp moved out of core into `@payloadcms/transformer-sharp`
2055
+ ### Sharp is now an optional file transformer #sharp-moved-out-of-core-into-payloadcmstransformer-sharp
1843
2056
 
1844
2057
  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`.
1845
2058
 
@@ -1899,7 +2112,7 @@ If you inject a custom Sharp build or version, pass it the same way:
1899
2112
 
1900
2113
  `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.
1901
2114
 
1902
- #### The stored `sizes` field on upload documents is renamed to `variants`
2115
+ #### Upload image data now uses variants
1903
2116
 
1904
2117
  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:
1905
2118
 
@@ -1959,7 +2172,7 @@ Registering any transformer under `upload.transformers` — including `sharpTran
1959
2172
 
1960
2173
  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.
1961
2174
 
1962
- ### Storage adapters always insert the `prefix` field now — `alwaysInsertFields` removed
2175
+ ### Storage prefixes are now always included
1963
2176
 
1964
2177
  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`.
1965
2178
 
@@ -1974,7 +2187,13 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
1974
2187
  - Remove `alwaysInsertFields` from your storage adapter or `cloudStoragePlugin` config — it has no effect and no longer exists on the option types.
1975
2188
  - 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.
1976
2189
 
1977
- ### `FileSizeImproved` removed — use `FileSize` ([#16593](https://github.com/payloadcms/payload/pull/16593))
2190
+ ### Upload collections retain originals and file history
2191
+
2192
+ 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).
2193
+
2194
+ **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.
2195
+
2196
+ ### File size types have been consolidated ([#16593](https://github.com/payloadcms/payload/pull/16593))
1978
2197
 
1979
2198
  `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.
1980
2199
 
@@ -1983,9 +2202,9 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
1983
2202
  + import type { FileSize } from 'payload'
1984
2203
  ```
1985
2204
 
1986
- ### `ImageSize.admin` — `disableListColumn`, `disableListFilter`, and `disableGroupBy` removed ([#16593](https://github.com/payloadcms/payload/pull/16593))
2205
+ ### Image size admin controls have been consolidated ([#16593](https://github.com/payloadcms/payload/pull/16593))
1987
2206
 
1988
- The three individual boolean props have been replaced with a single `disabled` object, consistent with the shape used by all other fields.
2207
+ 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.
1989
2208
 
1990
2209
  ```diff
1991
2210
  {
@@ -2002,7 +2221,7 @@ The three individual boolean props have been replaced with a single `disabled` o
2002
2221
 
2003
2222
  Run `npx @payloadcms/codemod --transform migrate-disabled-fields` to migrate automatically.
2004
2223
 
2005
- ### `db-mongodb`: `connectOptions.useFacet` removed ([#16612](https://github.com/payloadcms/payload/pull/16612))
2224
+ ### MongoDB queries no longer use facet aggregation ([#16612](https://github.com/payloadcms/payload/pull/16612))
2006
2225
 
2007
2226
  The `useFacet` option in `mongooseAdapter` config has been removed. Payload no longer uses `$facet` aggregation, so the option has no effect.
2008
2227
 
@@ -2014,7 +2233,7 @@ The `useFacet` option in `mongooseAdapter` config has been removed. Payload no l
2014
2233
  })
2015
2234
  ```
2016
2235
 
2017
- ### `plugin-search`: `apiBasePath` config option removed ([#16597](https://github.com/payloadcms/payload/pull/16597))
2236
+ ### Search plugin API paths are now derived automatically ([#16597](https://github.com/payloadcms/payload/pull/16597))
2018
2237
 
2019
2238
  The deprecated `apiBasePath` option on the search plugin has been removed. The plugin now derives the correct path from the root config automatically.
2020
2239
 
@@ -2026,7 +2245,7 @@ The sha1 HMAC fallback for API key authentication has been removed. API keys are
2026
2245
 
2027
2246
  **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.
2028
2247
 
2029
- ### `baseAPIKeyFields` was replaced by `createAPIKeyFields`
2248
+ ### API key fields now use a factory
2030
2249
 
2031
2250
  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.
2032
2251
 
@@ -2055,9 +2274,9 @@ createAPIKeyFields({
2055
2274
  })
2056
2275
  ```
2057
2276
 
2058
- ### `@payloadcms/plugin-mcp` refactored: config API, built-in tool inputs, and user API keys
2277
+ ### MCP plugin configuration and authentication have changed
2059
2278
 
2060
- The MCP plugin was refactored. The public config API, the built-in tool inputs, and API-key authentication changed. Update your plugin config and recreate MCP credentials as user API keys.
2279
+ `@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.
2061
2280
 
2062
2281
  **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 }`.
2063
2282
 
@@ -2230,7 +2449,7 @@ By default, MCP items require an authenticated user. Built-in collection and glo
2230
2449
 
2231
2450
  **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`.
2232
2451
 
2233
- ### `@payloadcms/ui/scss` export removed and legacy `--theme-*` tokens retired
2452
+ ### Admin UI styles now use CSS and semantic tokens
2234
2453
 
2235
2454
  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.
2236
2455
 
@@ -2306,7 +2525,7 @@ If you previously used `rest: false`, remove the property; omitting `rest` disab
2306
2525
  - `hasAPIKey` (3.x virtual field) is removed. Use `apiKeyLast4` and `docPermissions.fields.apiKey`.
2307
2526
  - Custom `access.read` on the generated `apiKey` field is inert — reads are hardcoded to deny.
2308
2527
 
2309
- ### Upload `abortOnLimit` now defaults to `true`
2528
+ ### Uploads now reject oversized files by default
2310
2529
 
2311
2530
  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.
2312
2531
 
@@ -2322,3 +2541,19 @@ export default buildConfig({
2322
2541
  },
2323
2542
  })
2324
2543
  ```
2544
+
2545
+ ### Nodemailer adapter now uses nodemailer 10 ([#18737](https://github.com/payloadcms/payload/pull/18737))
2546
+
2547
+ `@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`:
2548
+
2549
+ ```diff
2550
+ "dependencies": {
2551
+ - "nodemailer": "^9.1.1"
2552
+ + "nodemailer": "^10.1.1"
2553
+ },
2554
+ "devDependencies": {
2555
+ - "@types/nodemailer": "^8.0.0"
2556
+ }
2557
+ ```
2558
+
2559
+ If you use `transportOptions`, or pass no config, no changes are needed.