Payload CMS Release: 2.2.0

TL;DR

Payload CMS v2.2.0 brings significant improvements to the Lexical rich text editor, including better block handling, enhanced type generation, and various UI fixes. This release also introduces permission-based publish button visibility, improves transaction handling, and fixes several critical bugs across the platform. With over 4,900 changes across 167 files, this update focuses on stability, developer experience, and UI refinements.

Highlight of the Release

• Permission-based publish button visibility for more granular access control
• Improved rich text editor with better block handling and UI fixes
• Enhanced type generation for rich text adapters
• Fixed transaction handling for both synchronous operations and GraphQL
• New positioning options for Lexical plugins

Migration Guide

for v2.2.0

Rich Text Lexical Changes

If you're using the Lexical rich text editor with custom blocks, you'll need to be aware of the following changes:

1. Block Node Data Format: The format of block node data has changed. If you have custom code that directly accesses block node data, you may need to update it.

2. Block Fields Structure: Block fields are now wrapped in uniquely-named groups. If you have custom code that relies on the previous structure, you'll need to update it.

3. Type Generation: If you're using custom rich text adapters, you now have more control over type generation. Review the updated documentation for details on how to leverage this feature.

Plugin Development

If you're developing plugins for the Lexical editor:

1. New Position Property: You can now use the position: 'top' property for plugins to control their positioning in the UI.

2. TestRecorder Feature Plugin: If you're using the TestRecorder feature plugin, note that it now includes the 'use client' directive for Next.js compatibility.

Transaction Handling

If you're using custom transaction handling, especially with GraphQL:

1. Transaction Isolation: The transactionID isolation for GraphQL has been improved. Review your custom transaction handling code to ensure compatibility.

No database schema changes or breaking API changes were introduced in this release, so most applications should be able to upgrade without significant modifications.

Upgrade Recommendations

Recommendation Level: Recommended for all users

This release contains significant improvements to the rich text editor, transaction handling, and various UI fixes that benefit all users. There are no breaking changes reported, making it a safe upgrade for most projects.

How to Upgrade

1. Update your Payload CMS dependency to version 2.2.0:

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

2. If you're using the Lexical rich text editor with custom implementations, review the migration guide for potential adjustments to your code.

3. Test your application thoroughly after upgrading, particularly focusing on:

   • Rich text editing functionality
   • Block field operations
   • Transaction-heavy operations
   • GraphQL queries if you're using them

The improvements to type generation, block handling, and transaction isolation make this update particularly valuable for developers working on complex applications with rich content editing needs.

Bug Fixes

Rich Text Editor Fixes

• Nested Editor Issues:

  • Fixed issue where nested editors could lose focus while typing (#4139)
  • Fixed HTMLConverter to properly find nested Lexical fields (#4103)
  • Fixed buttons and dropdown buttons not being clickable in nested editors (#4113)

• UI and Interaction Fixes:

  • Fixed incorrect caret positioning when selecting the second line of multi-line paragraphs (#4165)
  • Fixed visual bug after rearranging blocks (#4171)
  • Fixed z-index issues causing select field dropdowns and slash menus to be hidden behind blocks (#4113)
  • Fixed array row data not being properly removed in blocks (#4209)

Core System Fixes

• Transaction Handling:

  • Fixed synchronous transaction errors (#4164)
  • Fixed transactionID isolation for GraphQL (#4095)

• UI and Accessibility:

  • Fixed live preview breakpoints and zoom options in dark mode (#4090)
  • Renamed tab button classname to prevent unintentional styling (#4121)
  • Fixed upload fit not being accounted for when editing focal point or crop (#4142)

• Internationalization and Access Control:

  • Updated Polish translations (#4134)
  • Fixed locale threading through to access routes from admin panel (#4183)

• Build and Integration:

  • Fully defined the define property for esbuild string replacement (#4099)
  • Fixed optional chaining after this as transpilers were not handling it well (#4145)
  • Added missing 'use client' directive to TestRecorder feature plugin (#4176)

• Field Validation:

  • Simplified block/array/hasMany-number field validations (#4052)

New Features

Rich Text Improvements

• Enhanced Type Generation: Rich text adapters can now control type generation with improved generated Lexical types (#4036)
• Permission-Based Publish Button: Added ability to hide the publish button based on user permissions (#4203)
• New Plugin Positioning: Added a new position: 'top' property for Lexical plugins, allowing more flexible UI customization (#4192)

Block Field Enhancements

• Improved Block Field Structure: Block fields are now wrapped in uniquely-named groups with an improved data format (#3995)
• Smarter Validation: Fields without fulfilled conditions are now properly skipped during validation (#4207)

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Performance Optimizations

• Rich Text Editor:

  • Upgraded Lexical packages from 0.12.2 to 0.12.4 with backported improvements (#4210)
  • Improved block handling with better data structure and rendering optimizations (#3995)

• Transaction Handling:

  • Enhanced transaction isolation for GraphQL operations, preventing data leakage between requests (#4095)
  • Improved synchronous transaction error handling for more reliable database operations (#4164)

• UI Rendering:

  • Fixed unnecessary re-renders in rich text blocks by addressing visual bugs after rearrangement (#4171)
  • Optimized nested editor focus handling to prevent performance degradation during typing (#4139)

Impact Summary

Payload CMS v2.2.0 delivers substantial improvements to the developer and content editor experience, with a particular focus on the Lexical rich text editor. The release addresses several critical issues that affected nested editors, block handling, and UI interactions, making the content editing experience more reliable and intuitive.

For developers, the enhanced type generation for rich text adapters provides better TypeScript support, while fixes to transaction handling improve the reliability of database operations. The addition of permission-based publish button visibility gives administrators more granular control over content workflows.

Content editors will benefit from numerous UI fixes, including improved caret positioning, better handling of nested editors, and fixed z-index issues that previously caused UI elements to be hidden. The live preview feature now works better in dark mode with improved breakpoints and zoom options.

Plugin developers gain new capabilities with the addition of the 'top' positioning property for Lexical plugins and fixes to the nested docs plugin.

With over 4,900 changes across 167 files, this release represents a significant step forward in Payload's evolution as a robust content management system, addressing pain points reported by the community while introducing targeted new features that enhance the platform's flexibility.

Full Release Notes