Payload CMS Release: 3.0.0-beta.46

TL;DR

PayloadCMS v3.0.0-beta.46 introduces significant enhancements to the rich text editor with sub-field hooks and localization support, improves type generation with diff checking, and fixes several UI and functionality issues. This release includes breaking changes to field hook methods and richText adapters that require migration steps for custom implementations.

Highlight of the Release

• Rich text editor now supports sub-field hooks and localization
• Fixed email sending in serverless environments
• Improved type generation with diff checking before writing
• Fixed list sorting preferences and block duplication
• Added missing export for useLeaf hook

Migration Guide

Migrating to v3.0.0-beta.46

Field Hook Methods

If you're using any of the following internal field hook methods, you'll need to update them to include the new required schemaPath and path props:

• afterChangeTraverseFields
• afterReadTraverseFields
• beforeChangeTraverseFields
• beforeValidateTraverseFields
• afterReadPromise

afterChange Field Hook

The value in the afterChange field hook is now the value AFTER previous hooks were run. Previously, this was the original value. Review your implementations to ensure they work with this changed behavior.

Custom RichText Adapters

If you've built your own richText adapter:

• Rename the populationPromises property to graphQLPopulationPromises
• Note that this is now only run for GraphQL (previously it ran for both GraphQL and REST API)
• To maintain REST API population, use hooks.afterRead to run population for the REST API

Custom Lexical Features

If you've built your own lexical features:

• Rename the populationPromises server feature property to graphQLPopulationPromises
• Note that this is now only run for GraphQL (previously it ran for both GraphQL and REST API)
• To maintain REST API population, use hooks.afterRead to run population for the REST API

Lexical Link and Upload Nodes

Serialized lexical link and upload nodes now have a new id property. While not breaking immediately, localization and hooks will not work for their fields until you migrate. To migrate:

• Re-save old documents on the new version to automatically add the id property
• Be aware that you'll see console logs for every lexical node that hasn't been migrated

Upgrade Recommendations

For Production Systems

If you're using PayloadCMS in production, we recommend caution when upgrading to this beta release due to the breaking changes in field hook methods and richText adapters. Before upgrading:

1. Review all custom field hooks and richText adapters in your codebase
2. Test the upgrade in a staging environment first
3. Plan for re-saving documents with lexical content to ensure proper migration of link and upload nodes

For Development Systems

For development environments, this upgrade is recommended as it brings important fixes and features that improve the developer and content editor experience.

Upgrade Steps

1. Update your package.json to reference v3.0.0-beta.46
2. Run npm install or yarn to update dependencies
3. Apply the necessary changes outlined in the migration guide
4. Test thoroughly, especially any custom field hooks or richText adapters

Bug Fixes

List Sort Preferences

Fixed an issue with list sort preferences (#6617). The system now properly sets preferences when list sort is set and uses defaultSort when defined in config and preferences are not set.

Email Sending in Serverless Environments

Fixed an issue where emails were not being properly awaited (#6457), which could cause serverless functions to terminate before emails were sent. The fix ensures that email sending operations are properly awaited before function completion.

UI Fixes

• Fixed an issue where the hideGutter property was being ignored in group fields (#6613)
• Added missing export for the useLeaf hook (#6693)

Block Duplication

Corrected the block duplicate action to ensure it works properly and added tests to prevent regression (#6589).

New Features

Rich Text Editor Enhancements

The Lexical rich text editor now supports sub-field hooks and localization, allowing for more granular control over content and multilingual capabilities. This major enhancement enables developers to apply hooks to specific fields within rich text content and properly handle localized content.

Type Generation Improvements

Added a new feature that diffs generated TypeScript types before writing them to disk. This optimization prevents unnecessary file writes when the generated types haven't changed, improving build performance and reducing file system operations.

Block Duplication

Fixed and improved the block duplication action, making it more reliable and consistent. This enhancement makes it easier for content editors to duplicate complex block structures without errors.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Type Generation Optimization

The new diff-before-write feature for generated TypeScript types improves build performance by avoiding unnecessary file system operations. When the generated types haven't changed from what's already on disk, the system will skip writing the file, reducing I/O operations and potentially speeding up builds in development environments.

Email Handling

The fix for unawaited emails improves the reliability of email sending, particularly in serverless environments where function execution time is limited. By properly awaiting email operations, the system ensures emails are sent before the function terminates.

Impact Summary

This release of PayloadCMS brings significant improvements to the rich text editor with localization support and sub-field hooks, making it more powerful for multilingual content management. The fixes for email sending in serverless environments and list sorting preferences address important usability issues.

However, the release includes several breaking changes that affect custom field hook implementations and richText adapters. Developers will need to update their code to accommodate these changes, particularly if they've built custom richText adapters or are using specific field hook methods.

The type generation improvements with diff checking provide a nice performance optimization for development workflows, reducing unnecessary file operations during builds.

Overall, this is an important beta release that moves PayloadCMS closer to a stable 3.0 release, with meaningful improvements for both developers and content editors, but requires careful migration planning due to the breaking changes.

Full Release Notes