@payloadcms/codemod 4.0.0-beta.6 → 4.0.0-beta.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/runbook/v4.mdx +93 -3
- package/package.json +1 -1
package/dist/runbook/v4.mdx
CHANGED
|
@@ -20,6 +20,30 @@ The codemod is idempotent and safe to run on a partially-migrated project.
|
|
|
20
20
|
|
|
21
21
|
## Breaking Changes
|
|
22
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
|
+
|
|
23
47
|
### Payload request creation is consolidated
|
|
24
48
|
|
|
25
49
|
Payload request creation now uses `createPayloadRequest` for local contexts and `createPayloadRequestFromWebRequest` to convert a Web `Request`. Admin context setup is exposed as `initAdminContext`.
|
|
@@ -120,6 +144,12 @@ A token is also rejected if its `collection` is not auth-enabled or has `disable
|
|
|
120
144
|
|
|
121
145
|
See [Token Data](../authentication/token-data) for the full token data shape.
|
|
122
146
|
|
|
147
|
+
### Sessions track their refreshes
|
|
148
|
+
|
|
149
|
+
Auth collections with `useSessions` (the default) now store two more fields on each session, `refreshCount` and `refreshedAt`. [Refresh tokens](../authentication/overview#refresh-tokens) use them to tell the latest refresh token apart from older ones.
|
|
150
|
+
|
|
151
|
+
On SQL adapters this adds two columns to each `<collection>_sessions` table, so existing projects need a database migration. In development the schema is pushed automatically; in production, generate a migration with `payload migrate:create` and run `payload migrate`. Existing sessions keep working, since an empty `refreshCount` counts as `0`. MongoDB needs no migration.
|
|
152
|
+
|
|
123
153
|
### Local API access is now enforced by default #overrideaccess-now-defaults-to-false-on-local-api-operations
|
|
124
154
|
|
|
125
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.
|
|
@@ -881,6 +911,42 @@ If you only used `useDocumentInfo` for `title` / `setDocumentTitle`, drop the im
|
|
|
881
911
|
|
|
882
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 }`).
|
|
883
913
|
|
|
914
|
+
### `Form` makes its own form-state requests
|
|
915
|
+
|
|
916
|
+
`Form` owns server form-state requests after field changes and successful saves. Document forms derive their request information from the surrounding document and operation providers. Nested forms identify their schema with `schemaPath`; bulk forms restrict their fields with `select`, and widget forms identify their entity with `widgetSlug`.
|
|
917
|
+
|
|
918
|
+
Remove callbacks that fetch and return server form state:
|
|
919
|
+
|
|
920
|
+
```diff
|
|
921
|
+
-const onChange = async ({ formState, submitted }) => {
|
|
922
|
+
- const { state } = await getFormState({
|
|
923
|
+
- collectionSlug,
|
|
924
|
+
- docPermissions,
|
|
925
|
+
- docPreferences: await getDocPreferences(),
|
|
926
|
+
- formState,
|
|
927
|
+
- operation: 'update',
|
|
928
|
+
- schemaPath,
|
|
929
|
+
- signal: controller.signal,
|
|
930
|
+
- skipValidation: !submitted,
|
|
931
|
+
- })
|
|
932
|
+
- return state
|
|
933
|
+
-}
|
|
934
|
+
-
|
|
935
|
+
-<Form initialState={initialState} onChange={[onChange]}>
|
|
936
|
+
+<Form initialState={initialState} schemaPath={schemaPath}>
|
|
937
|
+
```
|
|
938
|
+
|
|
939
|
+
A document's main form uses `isDocumentForm` and does not need `schemaPath`. It also owns document locking, stale-data detection, permission refreshes and preview URLs. Pass persistent read-only state with `readOnly`; temporary `disabled` or processing state does not make fields read-only on the server.
|
|
940
|
+
|
|
941
|
+
Plain custom forms without `isDocumentForm`, `schemaPath` or `widgetSlug` remain local, even when they receive `initialState` or are rendered inside a document provider. Initial state continues to be built before rendering the form.
|
|
942
|
+
|
|
943
|
+
BREAKING CHANGES:
|
|
944
|
+
|
|
945
|
+
- The return values of `onChange` and `onSuccess` are ignored. Use them for side effects only.
|
|
946
|
+
- `onChange` receives the merged state after an edit refresh or local submit validation, including invalid validation results. Validation notifications have `submitted: true`.
|
|
947
|
+
- Schema-backed forms with a local `onSubmit` validate on the server before committing. Remove `beforeSubmit` callbacks whose only purpose is fetching server form state. Invalid state or a validation request failure prevents the local commit.
|
|
948
|
+
- After a successful save, `Form` refreshes permissions and state before calling `onSuccess`. Creates skip the state refresh because they replace the form. A failed refresh does not change the successful save outcome or suppress `onSuccess`.
|
|
949
|
+
|
|
884
950
|
### Locale hooks can now return null
|
|
885
951
|
|
|
886
952
|
The return type of `useLocale` is now `Locale | null`. It returns `null` when localization is disabled or configured without any locales. In Payload 3, the hook was typed as `Locale` and returned an empty object when localization was unavailable.
|
|
@@ -1062,6 +1128,12 @@ Remove `diffMethod` from your props. If you passed it on to a diffing utility, p
|
|
|
1062
1128
|
}) => {
|
|
1063
1129
|
```
|
|
1064
1130
|
|
|
1131
|
+
### `root` removed from the `Endpoint` type
|
|
1132
|
+
|
|
1133
|
+
The deprecated `root` property has been removed from the `Endpoint` type. It has been typed as `never` since 3.0, so it couldn't be set, and Payload ignored it.
|
|
1134
|
+
|
|
1135
|
+
To serve a route outside of `routes.api`, add it to your app directly, e.g. as a [Next.js route handler](https://nextjs.org/docs/app/api-reference/file-conventions/route).
|
|
1136
|
+
|
|
1065
1137
|
### Collection after-operation hooks no longer report read operations
|
|
1066
1138
|
|
|
1067
1139
|
The deprecated `'read'` value for the `operation` argument of collection `afterOperation` hooks has been removed. Payload has not dispatched `afterOperation` with `operation: 'read'` for some time — the `find` and `findByID` operations report their own names (`'find'` and `'findByID'`) instead.
|
|
@@ -1184,9 +1256,11 @@ The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/d
|
|
|
1184
1256
|
|
|
1185
1257
|
The minimum supported Node.js version is now **24.22.1** (previously 18.20.2). Upgrade your runtime — along with any CI, Docker images, and deployment targets — to the latest node LTS version or newer before upgrading to 4.0.
|
|
1186
1258
|
|
|
1187
|
-
### Minimum supported Next.js version is now 16.4.
|
|
1259
|
+
### Minimum supported Next.js version is now 16.4.1 ([#16537](https://github.com/payloadcms/payload/pull/16537))
|
|
1188
1260
|
|
|
1189
|
-
Older versions of Next.js are no longer supported. Update Next.js to **16.4.
|
|
1261
|
+
Older versions of Next.js are no longer supported. Update Next.js to **16.4.1** or newer within the `16.x` release line.
|
|
1262
|
+
|
|
1263
|
+
React and React DOM must satisfy `^19.3.1`. TanStack Start applications also require `@vitejs/plugin-rsc` `^0.5.38`. These minimums include the fixes for [GHSA-xqc2-xf4c-x3h3](https://github.com/react/react/security/advisories/GHSA-xqc2-xf4c-x3h3) and its [Next.js advisory](https://github.com/vercel/next.js/security/advisories/GHSA-673q-mjm6-r5xr).
|
|
1190
1264
|
|
|
1191
1265
|
### Minimum supported TypeScript version is now 6.0.3 ([#16692](https://github.com/payloadcms/payload/pull/16692))
|
|
1192
1266
|
|
|
@@ -2159,10 +2233,26 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
|
|
|
2159
2233
|
|
|
2160
2234
|
### Upload collections retain originals and file history
|
|
2161
2235
|
|
|
2162
|
-
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
|
|
2236
|
+
Upload collections now store `original` metadata and a `prefix` and `_objectKey` for each stored file (the main file, `original`, and each variant), so saved versions can find their files. New uploads keep their uploaded filename. With a storage adapter, each new file is stored under its own `_objectKey` folder, so update any code or infrastructure that relies on the old object key. When a processed main file and its original share a filename, request the original with `?original=true`; `original.url` already includes it. With local storage, the original gets a counter name instead (for example `photo-1.png`). Files saved by earlier v4 beta releases with an `-original` filename keep that name and are still served. Custom storage adapters should handle the new `params.isOriginal` in `staticHandler`; see [Custom Storage Adapters](../upload/storage-adapters#custom-storage-adapters).
|
|
2163
2237
|
|
|
2164
2238
|
**Postgres and SQLite:** after updating, run `payload migrate:create`, check that it adds these columns to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` values until their next write.
|
|
2165
2239
|
|
|
2240
|
+
### Upload collections save crop and focal point edits in `_transforms`
|
|
2241
|
+
|
|
2242
|
+
Upload collections now have a `_transforms` JSON field that saves the crop and focal point, so an edit can start again from the retained original. See [Saved crop and focal point](../upload/overview#saved-crop-and-focal-point).
|
|
2243
|
+
|
|
2244
|
+
- `_transforms` is a reserved field name on upload collections. If an upload collection defines its own field named `_transforms`, rename it and move its data before you update.
|
|
2245
|
+
- `focalX` and `focalY` stay available and match `_transforms.focalPoint` when it is set. For a document saved before `_transforms` existed, the first write that saves `_transforms` copies its focal point into `_transforms`.
|
|
2246
|
+
- Replacing the file now sets `focalX` and `focalY` to the center, unless the request sends a new focal point. Before, the old values stayed on the document, but the new image sizes did not use them.
|
|
2247
|
+
|
|
2248
|
+
**Postgres and SQLite:** run `payload migrate:create`, check that it adds a `_transforms` column to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` until their next write.
|
|
2249
|
+
|
|
2250
|
+
Upload collections also have a core-controlled `_stored` field on the main file, on `original`, and on each entry under `variants`. A value of `false` marks an entry with no stored object. A missing or `null` value means stored, so existing documents need no data backfill. Payload ignores client writes to this field. It is hidden in the Admin Panel, but can appear in API responses; it is not a field-level hidden value. See [Files with no stored default](../upload/transformers#files-with-no-stored-default).
|
|
2251
|
+
|
|
2252
|
+
`_stored` is now reserved for these file entries. If an upload collection already defines a custom `_stored` field, rename it and move its data, including data in saved versions, before upgrading. Remove the old custom values from `_stored`: existing `false` values would otherwise be treated as files with no stored object, and writes to the custom field would be ignored.
|
|
2253
|
+
|
|
2254
|
+
**Postgres and SQLite:** run `payload migrate:create`, check that it adds the `_stored` columns for file entries in each upload collection and its versions, then run `payload migrate`. Existing rows keep `null`.
|
|
2255
|
+
|
|
2166
2256
|
### File size types have been consolidated ([#16593](https://github.com/payloadcms/payload/pull/16593))
|
|
2167
2257
|
|
|
2168
2258
|
`FileSizeImproved` has been merged into `FileSize`. The `url`, `width`, `height`, `filesize`, `mimeType`, and `filename` properties now accept `null` directly on `FileSize`, matching what the database stores for sizes that were not generated.
|