Payload CMS Release: 2.17.0

TL;DR

Payload CMS v2.17.0 introduces several improvements to internationalization support, fixes critical upload issues, and enhances UI elements. This release includes breaking changes to the richtext-lexical package's type system, requiring updates for developers using specific type definitions. The update also adds a new relationship object IDs plugin and improves documentation with new examples.

Highlight of the Release

• Breaking changes to richtext-lexical type system for improved consistency
• New plugin-relationship-object-ids package for enhanced relationship management
• Fixed critical upload issue when editing image crops or focal points
• Improved internationalization support across the admin UI
• Enhanced UI elements including step navigation breadcrumbs and form field IDs

Migration Guide

Breaking Changes in richtext-lexical

The following types have been removed from the richtext-lexical package:

• LexicalBlock
• RichTextFieldRequiredEditor
• FieldWithRichTextRequiredEditor

To migrate your code:

• Replace LexicalBlock with Block
• Replace RichTextFieldRequiredEditor with RichTextField
• Replace FieldWithRichTextRequiredEditor with Field

Example:

// Before
import { LexicalBlock, RichTextFieldRequiredEditor } from '@payloadcms/richtext-lexical';

// After
import { Block } from '@payloadcms/richtext-lexical';
import { RichTextField } from 'payload/types';

Upgrade Recommendations

This release contains breaking changes to the richtext-lexical package's type system, so developers using the removed types should plan to update their code accordingly.

For most users, this is a recommended upgrade that brings important bug fixes, especially for those working with image uploads and internationalization features.

To upgrade:

1. Update your Payload CMS version to 2.17.0:

   npm install [email protected]
   # or
   yarn add [email protected]
   

2. If you're using the richtext-lexical package, review your code for usage of the removed types and update according to the migration guide.

3. Test your application thoroughly, especially if you rely on image uploads or internationalization features.

Bug Fixes

• Upload Functionality: Fixed critical issue with image editing by safely accessing cookie header for uploads, resolving errors when changing crop or focal point of images (#6367)
• Localization Support: Fixed collection labels with locales not working when creating new documents (#5995)
• UI Improvements:
  • Fixed step-nav breadcrumbs ellipsis for better navigation experience (#6345)
  • Fixed API preview indentation for improved readability (#6152)
  • Removed letter spacing in loading overlay for script languages, enhancing compatibility (#4769)
• Example Project: Fixed Live Preview example by regenerating yarn lockfiles (#6356)

New Features

• Enhanced Internationalization Support: Added miscellaneous translations to API view and React select components, improving the multilingual experience (#6138)
• New Relationship Object IDs Plugin: Added a new plugin-relationship-object-ids package to enhance relationship field management (#6044)
• Improved Form Field Identification: Appended editDepth value to radio and checkbox IDs when inside drawers, ensuring proper form handling (#6181)
• Added Checkbox Field Translations: Improved internationalization for checkbox fields in collection views (#6167)

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

No specific performance improvements were highlighted in this release. The focus was primarily on feature enhancements, bug fixes, and type system improvements.

Impact Summary

Payload CMS 2.17.0 delivers significant improvements to the developer and content editor experience, particularly for teams working with internationalized content. The release fixes a critical issue with image uploads that was causing errors when editing crops or focal points, which will be especially valuable for media-heavy sites.

The breaking changes to the richtext-lexical type system are relatively minor and focused on type definitions, making the codebase more consistent but requiring updates for developers using the specific removed types.

The new relationship-object-ids plugin adds functionality for developers working with complex data relationships, while various UI improvements enhance the overall admin experience. These include better handling of step navigation breadcrumbs, improved form field identification in nested contexts, and enhanced internationalization support across multiple UI components.

For multilingual teams, the expanded translations in API views, React select components, and checkbox fields will make the content management experience more accessible and user-friendly.

Full Release Notes