Payload CMS Release: Release v2.4.0

TL;DR

Payload CMS 2.4.0 Release

This release brings significant improvements to the Payload CMS with a focus on rich text editing, live preview capabilities, and performance optimizations. The most notable change is the lazy loading of React components in the Lexical rich text editor to prevent client-only code from leaking into the server. This is a breaking change for users of @payloadcms/richtext-lexical. Other highlights include field-level configuration for relationships in the rich text editor, async live preview URLs, and several bug fixes related to uploads, relationships, and query validation.

Highlight of the Release

• Breaking change: Lazy loading of React components in @payloadcms/richtext-lexical to prevent client-only code from leaking into the server
• Field-level configuration for allowed relationships in Lexical rich text editor's Link and Relationship features
• Support for asynchronous live preview URLs
• Traditional Chinese translation added
• Fixed upload handling with improved validation flow
• Improved query validation with fixes for nested relationship fields

Migration Guide

for v2.4.0

Breaking Changes in @payloadcms/richtext-lexical

If you're using @payloadcms/richtext-lexical, this update requires changes to your code:

1. Package Version Synchronization:

   • You MUST update both payload and @payloadcms/richtext-lexical together
   • Keep versions in sync to avoid validation errors that could prevent Payload from starting

2. React Component Import Changes:

   • Any property in the Feature interface that accepts a React component now requires a function that imports the component instead

   Before:

   import { BlockIcon } from '../../lexical/ui/icons/Block'
   ...
   Icon: BlockIcon,
   

   After:

   // Remove the direct import
   ...
   Icon: () =>
     // @ts-expect-error
     import('../../lexical/ui/icons/Block').then((module) => module.BlockIcon),
   

   For default exports:

   // Remove the direct import
   ...
   Icon: () =>
     // @ts-expect-error
     import('../../lexical/ui/icons/Block'),
   

3. Type Changes:

   • The types for SanitizedEditorConfig and EditorConfig have changed
   • The lexical property now expects a function returning the LexicalEditorConfig instead of the config directly

4. Updated Import Paths: The following exports are now from @payloadcms/richtext-lexical/components instead of @payloadcms/richtext-lexical:

   • ToolbarButton
   • ToolbarDropdown
   • RichTextCell
   • RichTextField
   • defaultEditorLexicalConfig

   Update your imports accordingly if you use any of these components.

Upgrade Recommendations

For All Users

• Recommended Upgrade: This release contains important bug fixes and performance improvements that benefit all users. However, if you use @payloadcms/richtext-lexical, be aware of the breaking changes.

For @payloadcms/richtext-lexical Users

• Careful Planning Required: Due to the breaking changes in how React components are handled, plan your upgrade carefully and allocate time to update your code according to the migration guide.
• Package Synchronization: Ensure you update both payload and @payloadcms/richtext-lexical to compatible versions simultaneously.

For Users with Custom Features

• Code Review Needed: If you've created custom features for the Lexical editor, review and update your code to use the new lazy-loading pattern for React components.

Testing Recommendation

• Thorough Testing: Test your application thoroughly after upgrading, especially rich text editing, live preview functionality, and any custom features you've built.
• Staging Environment: Deploy to a staging environment first to verify everything works as expected before updating production.

Bug Fixes

Upload Handling

• Fixed upload editing errors when using the plugin-cloud integration
• Improved file upload process to properly handle validation before uploading files
• Added proper handling of null values in upload fields

Live Preview

• Fixed population of rich text uploads and relationships in live preview
• Improved data transmission by sending raw JavaScript objects through window.postMessage instead of JSON

Database and Queries

• Fixed an error in PostgreSQL adapter when sorting on a field that isn't configured
• Simplified query validation and fixed issues with nested relationship fields

Global Fields

• Fixed computation of default values on new globals

New Features

Rich Text Editor Enhancements

• Field-level relationship configuration: The Lexical rich text editor now allows configuring allowed relationships at the field level for both Link and Relationship features, providing more granular control over content relationships.
• Lazy loading of React components: Implemented lazy loading of React components in the Lexical rich text editor to prevent client-only code from leaking into the server, improving server-side performance.

Live Preview Improvements

• Async live preview URLs: Added support for asynchronous live preview URLs, allowing for dynamic generation of preview URLs based on document content.

UI and Developer Experience

• Path in Field Descriptions: Field descriptions now receive the field path, enabling more context-aware descriptions.
• Traditional Chinese translation: Added Traditional Chinese (zh_TW) localization support.

Developer API Enhancements

• Improved component architecture: Restructured exports in @payloadcms/richtext-lexical to better separate client and server code.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Server-Side Rendering

• Lazy loading of React components: The major architectural change in this release is the lazy loading of React components in the Lexical rich text editor. This prevents client-only code from being executed on the server, which can significantly improve server-side performance and reduce memory usage.

Data Handling

• Optimized data transmission: Live preview now sends raw JavaScript objects through window.postMessage instead of serializing and deserializing JSON, which can improve performance for complex documents.

Query Processing

• Simplified query validation: The query validation process has been simplified, which can improve performance when working with complex queries, especially those involving nested relationship fields.

Impact Summary

Payload CMS 2.4.0 introduces significant architectural improvements to the Lexical rich text editor, focusing on better separation between client and server code. This change improves server-side performance but requires code updates for users of @payloadcms/richtext-lexical.

The release also brings valuable enhancements to content management workflows, particularly in relationship handling and live preview capabilities. Content editors will benefit from improved upload handling and fixed issues with the live preview functionality.

For developers, the ability to configure allowed relationships at the field level provides more granular control over content relationships, while the support for async live preview URLs enables more dynamic preview experiences.

System administrators should note the importance of keeping payload and @payloadcms/richtext-lexical packages in sync to avoid validation errors.

Overall, this release represents a meaningful step forward in Payload's architecture and feature set, with the breaking changes being justified by the performance and maintainability improvements they enable.

Full Release Notes

import { BlockIcon } from '../../lexical/ui/icons/Block'
...
Icon: BlockIcon,

// import { BlockIcon } from '../../lexical/ui/icons/Block' // <= Remove this import
...
Icon: () =>
  // @ts-expect-error
  import('../../lexical/ui/icons/Block').then((module) => module.BlockIcon),

// import BlockIcon from '../../lexical/ui/icons/Block' // <= Remove this import
...
Icon: () =>
  // @ts-expect-error
  import('../../lexical/ui/icons/Block'),