@payloadcms/codemod 4.0.0-internal.44ac9c8 → 4.0.0-internal.4c2ee12

package/dist/runbook/v4.mdx

@@ -156,6 +156,31 @@ Run a typecheck after the codemod. Three patterns it cannot resolve:
 
 `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.
 
+### On-demand validation adds a `validate` operation
+
+The `Operation` type now includes `validate`. The `operation` argument for collection, global, and field `beforeValidate` and `beforeChange` hooks also includes `validate`.
+
+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`:
+
+```ts
+import type { CollectionBeforeChangeHook } from 'payload'
+
+const syncCustomer: CollectionBeforeChangeHook = async ({
+  data,
+  operation,
+}) => {
+  if (operation === 'validate') {
+    return data
+  }
+
+  await syncCustomerWithStripe(data)
+
+  return data
+}
+```
+
+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.
+
 ### Collection and Global Access Control callbacks receive `slug`
 
 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.
@@ -558,6 +583,39 @@ To migrate automatically, there's a codemod for this change available by running
 npx @payloadcms/codemod --transform migrate-field-component-types
 ```
 
+### Diff component props `comparisonValue` and `versionValue` renamed to `valueFrom` and `valueTo`
+
+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`.
+
+| Old prop          | New prop    | Description                                      |
+| ----------------- | ----------- | ------------------------------------------------ |
+| `comparisonValue` | `valueFrom` | Field value from the version being compared from |
+| `versionValue`    | `valueTo`   | Field value from the version being compared to   |
+
+```diff
+  import type { TextFieldDiffClientProps } from 'payload'
+  import type React from 'react'
+
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   comparisonValue,
+-   versionValue,
++   valueFrom,
++   valueTo,
+  }) => {
+    // ...
+  }
+```
+
+#### Codemod
+
+To migrate automatically, there's a codemod for this change available by running:
+
+```bash
+npx @payloadcms/codemod --transform rename-diff-value-props
+```
+
+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.
+
 ### `DefaultValue` function variant is now typed to allow returning a `Promise` ([#17522](https://github.com/payloadcms/payload/pull/17522))
 
 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`.
@@ -855,6 +913,49 @@ When a missing locale is already valid for the receiving API, optional chaining
 const locale = useLocale()?.code
 ```
 
+### `readOnly` removed from the `useField` return type
+
+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.
+
+Read `readOnly` from your field component's props instead:
+
+````diff
+'use client'
+import type { TextFieldClientComponent } from 'payload'
+import { useField } from '@payloadcms/ui'
+
+-export const MyField: TextFieldClientComponent = ({ path }) => {
+-  const { readOnly, value } = useField({ path })
++export const MyField: TextFieldClientComponent = ({ path, readOnly }) => {
++  const { value } = useField({ path })
+
+### Deprecated `TableColumnsProvider` props removed
+
+The following deprecated props have been removed from `TableColumnsProvider` and its `TableColumnsProviderProps` type:
+
+- `docs`
+- `enableRowSelections`
+- `listPreferences`
+- `preferenceKey`
+- `renderRowTypes`
+- `setTable`
+- `sortColumnProps`
+- `tableAppearance`
+
+`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`.
+
+```diff
+<TableColumnsProvider
+  collectionSlug={collectionSlug}
+  columnState={columnState}
+- enableRowSelections
+- preferenceKey={preferenceKey}
+- tableAppearance="condensed"
+>
+  {children}
+</TableColumnsProvider>
+````
+
 ### RichText adapter `i18n` property removed
 
 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.
@@ -916,6 +1017,52 @@ If an affected adapter or feature performs asynchronous work, move that work to
 
 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.
 
+### `headers` and `languageCode` removed from `AdminContext`
+
+The `headers` and `languageCode` properties have been removed from `AdminContext`, the object returned by `initAdminContext`. Both duplicated values that are already available on `req`:
+
+```diff
+const context = await initAdminContext(args)
+
+-const userAgent = context.headers.get('user-agent')
++const userAgent = context.req.headers.get('user-agent')
+
+-const languageCode = context.languageCode
++const languageCode = context.req.i18n.language
+```
+
+`req.i18n.language` is typed as `string`. Cast it to `AcceptedLanguages` if you need the narrower type.
+
+`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`.
+
+#### Codemod
+
+To migrate automatically, run:
+
+```bash
+npx @payloadcms/codemod --transform migrate-admin-context-properties
+```
+
+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.
+
+### `DiffMethod` type removed
+
+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`.
+
+### `diffMethod` prop removed from Diff components
+
+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.
+
+Remove `diffMethod` from your props. If you passed it on to a diffing utility, pass `'diffWordsWithSpace'` directly instead:
+
+```diff
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   diffMethod,
+    valueFrom,
+    valueTo,
+  }) => {
+```
+
 ### Collection `afterOperation` hook: `operation: 'read'` removed
 
 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.
@@ -1025,13 +1172,22 @@ If you use a `declare module` augmentation to extend `GeneratedDatabaseSchema` (
 
 Run `npx @payloadcms/codemod --transform migrate-db-types-subpath` to migrate automatically. The codemod handles import declarations, re-export declarations, and `declare module` augmentations.
 
+### `findMigrationDir` removed from `@payloadcms/drizzle`
+
+The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/drizzle`. Import it from `payload` instead:
+
+```diff
+- import { findMigrationDir } from '@payloadcms/drizzle'
++ import { findMigrationDir } from 'payload'
+```
+
 ### Minimum supported Node.js version is now 24.15.0 ([#16540](https://github.com/payloadcms/payload/pull/16540))
 
 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.
 
-### Minimum supported Next.js version is now 16.2.6 ([#16537](https://github.com/payloadcms/payload/pull/16537))
+### Minimum supported Next.js version is now 16.4.0 ([#16537](https://github.com/payloadcms/payload/pull/16537))
 
-Older versions of Next.js are no longer supported. Update Next.js to **16.2.6** or newer.
+Older versions of Next.js are no longer supported. Update Next.js to **16.4.0** or newer.
 
 ### Minimum supported TypeScript version is now 6.0.3 ([#16692](https://github.com/payloadcms/payload/pull/16692))
 
@@ -1087,9 +1243,9 @@ The deprecated `isHTMLElement` utility has been removed from `@payloadcms/richte
 
 `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.
 
-### Lexical: vendored `@lexical/markdown` fork removed and lexical upgraded to `0.50.0`
+### Lexical: vendored `@lexical/markdown` fork removed and lexical upgraded to `0.52.0`
 
-`@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.50.0`, and `@payloadcms/richtext-lexical/lexical/markdown` is a pure passthrough of `@lexical/markdown`.
+`@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`.
 
 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.
 
@@ -1113,7 +1269,16 @@ If you keep calling `$convertFromMarkdownString` directly, pass `editorConfig.fe
 
 **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.
 
-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.50.0`. None of them require action for typical Payload usage.
+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.
+
+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:
+
+- Lexical packages are ESM only. Use ESM imports; CommonJS `require()` needs Node.js 20.19 or later.
+- `SELECTION_CHANGE_COMMAND` now runs before DOM reconciliation. Defer DOM lookups and floating UI positioning with `$onUpdate(() => editor.read('latest', callback))`, or use an update listener for work that should run after every commit.
+- Call `node.getLatest().exportJSON()` when serializing a node reference retained across an update. Payload continues to write the full JSON format; compact export is not enabled.
+- `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[]`.
+- `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.
+- `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.
 
 ### Lexical: `EXPERIMENTAL_TableFeature` renamed to `TableFeature`
 
@@ -1131,6 +1296,43 @@ The table feature is no longer experimental, so it drops its prefix.
 
 Stored content is unaffected.
 
+### Lexical: `LexicalEditorProps` renamed to `LexicalEditorArgs`
+
+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.
+
+````diff
+- import type { LexicalEditorProps } from '@payloadcms/richtext-lexical'
++ import type { LexicalEditorArgs } from '@payloadcms/richtext-lexical'
+
+### Lexical: `UploadDataImproved` replaced by `UploadData` ([#18606](https://github.com/payloadcms/payload/pull/18606))
+
+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`:
+
+```ts
+import type { UploadData } from '@payloadcms/richtext-lexical'
+````
+
+### Lexical: the `version` of nodes is ignored
+
+Lexical deprecated the `version` property of serialized nodes, and now ignores it when it loads a document. Payload no longer reads it either.
+
+**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:
+
+- Block nodes whose fields were wrapped in an extra `data` object (`fields.data`)
+- Relationship and upload nodes that stored the whole related document in `value`, instead of its ID
+
+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:
+
+```ts
+import { upgradeLexicalData } from '@payloadcms/richtext-lexical'
+
+await upgradeLexicalData({ payload })
+```
+
+**`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.
+
+**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.
+
 ### Field `typescriptSchema` renamed to `jsonSchema`
 
 `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.
@@ -1668,6 +1870,8 @@ If you typed `clientUploads.access`, replace `ClientUploadsAccess` with `UploadI
 
 #### If you maintain a custom storage adapter
 
+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.
+
 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.
 
 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.
@@ -1809,11 +2013,13 @@ Run `npx @payloadcms/codemod --transform migrate-azure-chunk-large-files` to rem
 
 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`.
 
-This affects three things:
+This affects four things:
 
 1. The top-level `sharp` config property has been removed. Passing a Sharp instance now happens through `sharpTransformer({ sharp })` instead.
 2. Per-collection Sharp options — `constructorOptions`, `formatOptions`, `resizeOptions`, `trimOptions`, and `withMetadata` — have been removed from `CollectionConfig['upload']`. They're now authored through `sharpTransformer({ collections })`.
+   - `imageSizes` has also been removed from `CollectionConfig['upload']`. Image sizes are now declared as `variants` on `sharpTransformer({ collections: { <slug>: { variants } } })`. The entries themselves (`name`, `width`, `height`, `generateImageName`, and so on) are unchanged. A collection that still sets `upload.imageSizes` fails the build.
 3. `sharp` is no longer a dependency of `payload` at all (previously a `devDependency`, not a runtime `dependency`). Install `@payloadcms/transformer-sharp` explicitly.
+4. The Sharp-specific types `SharpDependency`, `ImageUploadFormatOptions`, `ImageUploadTrimOptions`, and `SharpImageSizeOptions` are no longer exported from `payload`. Import `SharpDependency` from `@payloadcms/transformer-sharp`. For the option types, use `SharpCollectionConfig['formatOptions']`, `SharpCollectionConfig['trimOptions']`, and `NonNullable<SharpCollectionConfig['variants']>[number]` from the same package.
 
 ```sh
 pnpm add @payloadcms/transformer-sharp
@@ -1841,7 +2047,7 @@ pnpm add @payloadcms/transformer-sharp
 +         collections: {
 +           media: {
 +             resizeOptions: { width: 2048, height: 2048 },
-+             imageSizes: [{ name: 'thumbnail', width: 400, height: 300 }],
++             variants: [{ name: 'thumbnail', width: 400, height: 300 }],
 +           },
 +         },
 +       }),
@@ -1850,9 +2056,9 @@ pnpm add @payloadcms/transformer-sharp
   })
 ```
 
-Run `npx @payloadcms/codemod --transform migrate-sharp-to-transformer` to migrate automatically. The codemod moves a top-level `sharp` dependency and inline collection Sharp options into `sharpTransformer({ collections })`, appends to an existing `upload.transformers` array if you already have one, and leaves anything it can't safely rewrite in place with a note — for example, a `collections` array built by a function call, or a collection defined outside the `buildConfig` call. Review those manually.
+Run `npx @payloadcms/codemod --transform migrate-sharp-to-transformer` to migrate automatically. The codemod moves a top-level `sharp` dependency and inline collection Sharp options — including `crop` and `focalPoint` — into `sharpTransformer({ collections })` (writing `imageSizes` as `variants`), appends to an existing `upload.transformers` array if you already have one, and leaves anything it can't safely rewrite in place with a note — for example, a `collections` array built by a function call, or a collection defined outside the `buildConfig` call. Review those manually. For a config that already registers `sharpTransformer`, it only renames `imageSizes` to `variants` inside the existing `sharpTransformer` call and flags a leftover top-level `sharp` property; it doesn't move any remaining collection options.
 
-`imageSizes`, `crop`, and `focalPoint` are still readable at `collection.upload.imageSizes`/`.crop`/`.focalPoint` — `sharpTransformer` writes a projection of what you configure back onto the sanitized collection at startup, so the Admin Panel, generated types, and the stored `sizes` shape on your documents are unchanged. This write-back is why `crop`/`focalPoint`/`imageSizes` are not in the list of removed options above — only the Sharp-specific processing options moved.
+Your `variants`, `crop`, and `focalPoint` are readable at `collection.upload.variants`/`.crop`/`.focalPoint` on the **sanitized** config (for example `req.payload.collections.media.config.upload.variants`). Code that read the sanitized `upload.imageSizes` in 3.x must read `upload.variants` instead. `sharpTransformer` writes a projection of what you configure back onto the sanitized collection at startup, so the Admin Panel and the rest of core see the same configuration. For a collection configured on `sharpTransformer`, a `crop` or `focalPoint` set on the transformer replaces the collection's own value; one left unset there keeps the collection's. Neither `imageSizes` nor `variants` can be set on the collection at all.
 
 If you inject a custom Sharp build or version, pass it the same way:
 
@@ -1861,7 +2067,67 @@ If you inject a custom Sharp build or version, pass it the same way:
 + sharpTransformer({ sharp: myCustomSharp })
 ```
 
-`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 `imageSizes`, as in Payload 3.x. 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.
+`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.
+
+#### The stored `sizes` field on upload documents is renamed to `variants`
+
+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:
+
+```diff
+- doc.sizes?.thumbnail?.url
++ doc.variants?.thumbnail?.url
+
+- where: { 'sizes.thumbnail.filename': { equals: 'photo-400x300.png' } }
++ where: { 'variants.thumbnail.filename': { equals: 'photo-400x300.png' } }
+
+- select: { sizes: { thumbnail: true } }
++ select: { variants: { thumbnail: true } }
+```
+
+GraphQL queries select `variants { thumbnail { url } }` instead of `sizes { thumbnail { url } }`, and regenerated types expose `variants?: { ... }` (and `variants?: T | { ... }` on the `*Select` types) in place of `sizes`. Update any frontend code that reads `media.sizes`, including values you pass to helpers such as `getBestFitFromSizes({ sizes: doc.variants })`.
+
+Existing documents must be migrated. Create the predefined migration for your database adapter and run it:
+
+<Banner type="warning">
+  Payload 4 uses `variants` as the top-level field for generated upload
+  variants. If an upload collection already defines a custom field named
+  `variants`, rename that field before you run the predefined migration. Choose
+  a new name, update your config, and write a custom migration that moves the
+  existing custom data from `variants` to the new field. Then run the predefined
+  `sizes-to-variants` migration. If legacy `sizes` data or columns and custom
+  `variants` data or columns are both present, the predefined migration stops
+  before it changes data or indexes. It cannot choose a new name or merge this
+  custom data for you.
+</Banner>
+
+```sh
+# MongoDB
+payload migrate:create --file @payloadcms/db-mongodb/sizes-to-variants
+# Postgres
+payload migrate:create --file @payloadcms/db-postgres/sizes-to-variants
+# Vercel Postgres
+payload migrate:create --file @payloadcms/db-vercel-postgres/sizes-to-variants
+# SQLite
+payload migrate:create --file @payloadcms/db-sqlite/sizes-to-variants
+# Cloudflare D1
+payload migrate:create --file @payloadcms/db-d1-sqlite/sizes-to-variants
+
+payload migrate
+```
+
+**Postgres and SQLite (including Vercel Postgres and D1):** the columns are renamed in place from `sizes_<name>_<property>` to `variants_<name>_<property>`, on each upload collection's table and its versions table, along with their indexes. Use the predefined migration above **instead of** a plain `payload migrate:create` for this change. A generated migration would drop the `sizes_*` columns and add new `variants_*` columns, losing the stored image size data. The predefined migration also writes the schema snapshot, so the next generated migration starts from the renamed columns.
+
+On MongoDB the migration renames `sizes` (and `version.sizes` on versions) with `$rename` and re-creates the indexes on those fields under the new path. Run the migration before the upgraded app writes to upload documents.
+
+#### The file endpoint changes once any transformer is registered
+
+Registering any transformer under `upload.transformers` — including `sharpTransformer()` with dynamic resizing off — routes every file request through the transformer-aware handler:
+
+- A file must belong to an upload document to be served. A file that exists in storage without a matching document now returns `404`.
+- For files whose MIME type a transformer declares (every image, with `sharpTransformer()`), `access.read` can run twice per request: once with `req.fileTransform` set to `true` to decide a possible transform, and once without it for an ordinary read. Keep `access.read` cheap, and use `req.fileTransform` to restrict transformed reads — see [Access control](../upload/transformers#access-control).
+- Responses produced by a transformer always carry Payload's CORS headers, which `modifyResponseHeaders` can't override.
+
+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.
 
 ### Storage adapters always insert the `prefix` field now — `alwaysInsertFields` removed
 
@@ -1878,6 +2144,12 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
 - Remove `alwaysInsertFields` from your storage adapter or `cloudStoragePlugin` config — it has no effect and no longer exists on the option types.
 - 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.
 
+### Upload collections retain originals and file history
+
+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 source under an `-original` filename. Update any code or infrastructure that relies on the old filename, URL, or object key.
+
+**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.
+
 ### `FileSizeImproved` removed — use `FileSize` ([#16593](https://github.com/payloadcms/payload/pull/16593))
 
 `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.
@@ -2132,6 +2404,8 @@ By default, MCP items require an authenticated user. Built-in collection and glo
 
 **Dependencies.** The plugin now builds on `@modelcontextprotocol/server` instead of `@modelcontextprotocol/sdk` + `mcp-handler`. It no longer depends on Zod directly; its built-in tools use the Zod Mini export from `payload`. If your custom tools use regular Zod, install Zod v4 in your project and import it directly.
 
+**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`.
+
 ### `@payloadcms/ui/scss` export removed and legacy `--theme-*` tokens retired
 
 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.

package/dist/transforms/migrate-admin-context-properties/basic.input.js

@@ -0,0 +1,32 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, headers, languageCode, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        headers,
+        importMap: args.importMap,
+        languageCode,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { headers: requestHeaders, languageCode, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).headers.get('user-agent');
+export const getDirection = (context)=>context.languageCode === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ headers })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.input.js.map

package/dist/transforms/migrate-admin-context-properties/basic.input.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.input.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'headers' | 'languageCode' | 'req'>\n\ntype LanguageCode = AdminContext['languageCode']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, headers, languageCode, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    headers,\n    importMap: args.importMap,\n    languageCode,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { headers: requestHeaders, languageCode, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.languageCode === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ headers }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","headers","languageCode","permissions","req","user","data","importMap","userAgent","get","getTheme","requestHeaders","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,OAAO,EAAEC,YAAY,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGN;IAEnE,MAAMO,OAAO,MAAMX,kBAAkB;QACnCK;QACAC;QACAM,WAAWT,KAAKS,SAAS;QACzBL;QACAC;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWT,QAAQE,OAAO,CAACQ,GAAG,CAAC;IAAc;AAC9D;AAEA,OAAO,eAAeC,SAASZ,IAA0B;IACvD,MAAM,EAAEG,SAASU,cAAc,EAAET,YAAY,EAAEG,IAAI,EAAE,GAAG,MAAMT,iBAAiBE;IAE/E,OAAO;QAAEI;QAAcU,OAAOD,eAAeF,GAAG,CAAC;QAAgCJ;IAAK;AACxF;AAEA,OAAO,MAAMQ,eAAe,OAAOf,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGG,OAAO,CAACQ,GAAG,CAAC,cAAa;AAE1D,OAAO,MAAMK,eAAe,CAACf,UAC3BA,QAAQG,YAAY,KAAK,OAAO,QAAQ,MAAK;AAE/C,OAAO,MAAMa,oBAAoB,CAAC,EAAEd,OAAO,EAAgB,GAAKA,QAAQQ,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/basic.output.js

@@ -0,0 +1,30 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        importMap: args.importMap,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.req.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).req.headers.get('user-agent');
+export const getDirection = (context)=>context.req.i18n.language === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ req: { headers } })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.output.js.map

package/dist/transforms/migrate-admin-context-properties/basic.output.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.output.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'req'>\n\ntype LanguageCode = AdminContext['req']['i18n']['language']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    importMap: args.importMap,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.req.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).req.headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.req.i18n.language === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ req: { headers } }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","permissions","req","user","data","importMap","userAgent","headers","get","getTheme","requestHeaders","i18n","language","languageCode","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGJ;IAE5C,MAAMK,OAAO,MAAMT,kBAAkB;QACnCK;QACAK,WAAWP,KAAKO,SAAS;QACzBJ;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWP,QAAQG,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC;IAAc;AAClE;AAEA,OAAO,eAAeC,SAASX,IAA0B;IACvD,MAAM,EAAEI,KAAK,EAAEK,SAASG,cAAc,EAAEC,MAAM,EAAEC,UAAUC,YAAY,EAAE,EAAE,EAAEV,IAAI,EAAE,GAAG,MAAMP,iBAAiBE;IAE5G,OAAO;QAAEe;QAAcC,OAAOJ,eAAeF,GAAG,CAAC;QAAgCL;IAAK;AACxF;AAEA,OAAO,MAAMY,eAAe,OAAOjB,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGI,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC,cAAa;AAE9D,OAAO,MAAMQ,eAAe,CAACjB,UAC3BA,QAAQG,GAAG,CAACS,IAAI,CAACC,QAAQ,KAAK,OAAO,QAAQ,MAAK;AAEpD,OAAO,MAAMK,oBAAoB,CAAC,EAAEf,KAAK,EAAEK,OAAO,EAAE,EAAgB,GAAKA,QAAQC,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/index.d.ts

@@ -0,0 +1,3 @@
+import type { Transform } from '../../types.js';
+export declare const migrateAdminContextProperties: Transform;
+//# sourceMappingURL=index.d.ts.map

package/dist/transforms/migrate-admin-context-properties/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transforms/migrate-admin-context-properties/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAwC/C,eAAO,MAAM,6BAA6B,EAAE,SA8J3C,CAAA"}