●Change8

Migrating to Payload CMS v3.28.0

Version v3.28.0 introduces 1 breaking change. This guide details how to update your code.

Released: 3/11/2025

1
Breaking Changes
3
Migration Steps
7
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

withPayloadlexicalpayload-locked-documentsfield validate functiongraphql field namesi18n configurationupload.displayPreview

Breaking Changes

●Issue #1

Projects relying on server-only Payload dependencies being bundled during development might see unexpected behavior due to the new opt-in compilation performance flag. To maintain previous behavior, ensure you do not enable `devBundleServerPackages: false` in `withPayload` configuration.

Migration Steps

  1. 1
    To enable compilation performance improvements, update your `next.config.js` to include `{ devBundleServerPackages: false }` in the `withPayload` call: `export default withPayload(nextConfig, { devBundleServerPackages: false })`.
  2. 2
    If you manually installed `lexical`, update it to version `0.27.1`.
  3. 3
    If encountering richtext-lexical errors after the upgrade, perform a clean reinstall: 1. Delete `node_modules`. 2. Delete your lockfile (e.g., `pnpm-lock.json`). 3. Reinstall dependencies (e.g., `pnpm install`).

Release Summary

This release focuses on significant performance improvements via an opt-in compilation flag and upgrades the core Lexical dependency to 0.27.1, alongside numerous bug fixes across database, GraphQL, and UI components.

Need More Details?

View the full release notes and all changes for Payload CMS v3.28.0.

View Full Changelog