Payload CMS Release: 3.0.0-beta.54

TL;DR

PayloadCMS v3.0.0-beta.54 introduces significant improvements and breaking changes to the codebase. This release focuses on enhancing type safety, standardizing component naming conventions, and improving the architecture of the rich text editor. Key improvements include better dependency management, standardized field exports, and simplified feature creation in the Lexical rich text editor. Several bug fixes address issues with upload handlers, select options, JSON field validation, and image cropping. Developers using PayloadCMS should pay special attention to the breaking changes in import paths and type definitions when upgrading.

Highlight of the Release

• Standardized field component naming convention for better semantics and consistency
• Improved architecture for Lexical rich text editor with clear client/server separation
• Enhanced type safety with better type narrowing for relationship fields
• Performance improvements by replacing bloated dependencies
• Fixed several bugs including select options updating, image cropping, and upload handlers

Migration Guide

Import Path Changes for UI Components

If you're using components from the unbundled @payloadcms/ui package, you'll need to update your import paths:

Old:

import { Text } from '@payloadcms/ui/fields/Text'

New:

import { TextField } from '@payloadcms/ui/fields/Text'

Note: If you're importing from the bundled version, your imports likely won't need to change:

import { TextField } from '@payloadcms/ui'

Rich Text Lexical Export Changes

The exports have been reorganized into server-only and client-only exports:

• @payloadcms/richtext-lexical - Server-only exports
• @payloadcms/richtext-lexical/client - Client-only exports

If your imports don't resolve after upgrading, change them to use one of these paths depending on whether you're on the server or client.

Rich Text Feature Creation Changes

Several naming changes have been made to the Lexical feature creation API:

• ClientComponent has been renamed to ClientFeature
• serverFeatureProps has been renamed to sanitizedServerFeatureProps
• clientFeatureProps has been renamed to sanitizedClientFeatureProps
• FeatureProviderProviderServer type now expects 3 generics instead of 2
• FeatureProviderProviderClient type now expects 2 generics instead of 1

Upgrade Recommendations

This is a beta release with breaking changes, so careful testing is recommended before upgrading production environments.

1. Review Breaking Changes: Pay special attention to the import path changes for UI components and the restructured exports in the rich text editor.

2. Update Import Paths: Update any imports from unbundled UI components to use the new naming convention with the Field suffix.

3. Adjust Rich Text Feature Usage: If you've created custom Lexical features, update your code to match the new naming conventions and type structures.

4. Test Thoroughly: Test your application thoroughly after upgrading, especially any custom components, rich text editor implementations, and relationship fields.

5. Review Documentation: Check the updated documentation for rich text features and other components to ensure you're following the latest patterns.

For projects with extensive customizations of the rich text editor or heavy use of relationship fields, plan for additional time to adapt to the type changes and new export structure.

Bug Fixes

UI and Field Components

• Fixed select options not updating when the options prop changes
• Standardized named field exports by appending Field to component names
• Fixed image cropping by sending pixel values to the server instead of percentage values

Validation and Request Handling

• Fixed JSON field defaultValue Joi validation
• Now allowing request mutation inside upload handlers
• Prevented dependency version checker from finding node_modules outside the project
• Removed error throwing when no dependencies are found

New Features

Type Improvements

• Enhanced type narrowing for relationTo props on filterOptions, relationship fields, and upload fields
• Improved type narrowing for arguments of lexical relationship, link, and upload features

Rich Text Editor Enhancements

• Properly defined client-only and server-only exports with clear separation
• Simplified creation of features with improved component architecture
• Added documentation for building custom Lexical features

Performance Optimizations

• Replaced bloated deep-equal dependency with more efficient alternatives
• Minimized usage of the qs library to improve performance

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Dependency Optimization

• Replaced the bloated deep-equal dependency with more efficient alternatives
• Minimized usage of the qs library for better performance

Component Architecture

• Improved the architecture of the Lexical rich text editor with clearer separation of client and server components
• Simplified feature creation process to reduce overhead

Impact Summary

This release brings significant architectural improvements to PayloadCMS, particularly in the rich text editor and type system. The standardization of field component naming and the clear separation of client/server code in the Lexical editor will lead to more maintainable and predictable code.

The breaking changes primarily affect developers who have created custom components or are using the rich text editor extensively. The improved type narrowing for relationship fields will catch more errors at compile time, leading to more robust applications.

Performance improvements from dependency optimization will benefit all users, especially those with larger projects. The bug fixes address several pain points, including select options not updating properly and image cropping issues.

Overall, this release represents an important step toward the final v3.0.0 release, with a focus on stability, performance, and developer experience. While the breaking changes require some migration effort, they establish better patterns that will make future development more straightforward.

Full Release Notes

import { Text } from '@payloadcms/ui/fields/Text'

import { TextField } from '@payloadcms/ui/fields/Text'

import { TextField } from '@payloadcms/ui'