Payload CMS Release: 3.0.0-beta.53

TL;DR

PayloadCMS v3.0.0-beta.53 introduces a breaking change by renaming @payloadcms/ui/client to @payloadcms/ui to improve IDE auto-completions. It also enhances rich text functionality by making request objects available to HTML converters and using data loaders for better performance. Several bug fixes address issues with unflattening JSON objects, empty string default values in text fields, and UI imports across plugins.

Highlight of the Release

• Breaking change: @payloadcms/ui/client exports renamed to @payloadcms/ui
• Rich text improvements with request object availability to HTML converters
• Performance optimization using data loaders for upload node population
• Fixed issue with unflattening JSON objects containing keys with periods
• Added support for empty strings as default values in text-like fields

Migration Guide

Migrating from @payloadcms/ui/client to @payloadcms/ui

To migrate from the previous version, you'll need to update all imports that use @payloadcms/ui/client to use @payloadcms/ui instead.

You can do this with a simple find and replace across your entire project:

1. Find: @payloadcms/ui/client
2. Replace with: @payloadcms/ui

This change affects all UI component imports from the PayloadCMS UI package.

Upgrade Recommendations

This release contains a breaking change related to UI imports, but the migration is straightforward.

Recommended for:

• Developers who want to benefit from improved IDE auto-completions
• Projects that need the bug fixes for text field default values and JSON unflattening
• Applications that would benefit from the performance improvements in rich text handling

When to upgrade:

• If you're already using the beta version, upgrading is recommended as the breaking change is minimal and easy to implement
• Plan for a small amount of time to update your imports from @payloadcms/ui/client to @payloadcms/ui
• Test your application thoroughly after upgrading, especially if you rely heavily on rich text fields with uploads

Bug Fixes

Fixed JSON Unflattening with Period-Containing Keys

Fixed an issue where the unflatten function would incorrectly process JSON objects when they contained keys with periods (.). This ensures proper handling of complex object structures with special characters in key names.

Support for Empty String Default Values

Resolved a bug that prevented using empty strings ('') as default values for text-like fields including:

• Text fields
• Textarea fields
• Email fields
• Code fields

This improvement allows developers to ensure values are always strings instead of null/undefined when needed.

UI Import Fixes

Fixed UI imports across all plugins and removed UI subpath exports within the monorepo, ensuring consistent import patterns throughout the codebase.

New Features

Renamed UI Package Path for Better Developer Experience

The path to UI components has been renamed from @payloadcms/ui/client to simply @payloadcms/ui. This change significantly improves import auto-completions in IDEs like WebStorm that don't fully support package.json exports.

Enhanced Rich Text Functionality

The rich text Lexical editor now makes the request object (req) available to HTML converters. Additionally, it now uses req.dataLoader instead of payload.findByID for upload node population, which improves performance and efficiency when converting rich text content that contains uploads.

Performance Improvements

Rich Text Performance Optimization

The rich text Lexical editor now uses req.dataLoader instead of payload.findByID for upload node population. This change leverages data loaders to batch and cache database queries, resulting in more efficient data fetching when converting rich text content that contains multiple uploads or references.

Impact Summary

This release introduces a breaking change by renaming the UI package path, but provides a straightforward migration path. The change significantly improves developer experience with better IDE auto-completions.

Performance improvements in rich text handling will benefit both developers and content editors, especially for content with multiple uploads or references. The bug fixes address important issues with JSON handling and default values in text fields.

The package structure has been simplified and refactored, particularly in the richtext-lexical package, making the codebase more maintainable and easier to work with.

Overall, this beta release continues to refine the v3 experience with quality-of-life improvements for developers while maintaining stability for existing functionality.

Full Release Notes