Payload CMS Release: Release v2.5.0

TL;DR

Payload CMS v2.5.0 introduces significant enhancements to the rich text editing experience with major updates to the Lexical editor, improved SEO plugin integration, and numerous bug fixes. This release focuses on developer experience improvements, better field handling, and performance optimizations across the platform. Notable changes include breaking changes to the Lexical rich text editor, improved URL validation, and better handling of relationship fields.

Highlight of the Release

• SEO plugin renamed from 'meta' to 'seo' with improved description generation and title handling
• Major updates to Lexical rich text editor with breaking changes to component imports and link handling
• New context property added to auth and globals local API
• Improved form submission emails functionality
• Better handling of relationship fields with optimized querying
• Enhanced admin navigation with smoother transitions
• Added max file size labels to media fields for better user experience

Migration Guide

Migrating from v2.4.0 to v2.5.0

Breaking Changes in @payloadcms/richtext-lexical

1. TreeviewFeature Rename

   • Rename all imports of TreeviewFeature to TreeViewFeature (with capital "V")

2. Link Node Data Format Change

   • If you're reading link node data in your frontend code, update your code:
   • Old format: fields.doc.value.id
   • New format: fields.doc.value

3. React Component Imports

   • If you're importing React components from Lexical features, update to use dynamic imports:

   // Old
   import { BlockIcon } from '../../lexical/ui/icons/Block'
   ...
   Icon: BlockIcon,
   
   // New
   Icon: () =>
     import('../../lexical/ui/icons/Block').then((module) => module.BlockIcon),
   

4. ToolbarDropdown Component

   • The ToolbarDropdown component now requires a mandatory sectionKey prop

5. Package Exports Changes

   • The following exports are now from @payloadcms/richtext-lexical/components:
     • ToolbarButton
     • ToolbarDropdown
     • RichTextCell
     • RichTextField
     • defaultEditorLexicalConfig

6. Version Synchronization

   • Ensure you update both Payload and @payloadcms/richtext-lexical together to avoid validation errors

SEO Plugin Migration

• If you were using the meta plugin, it has been renamed to SEO
• Review your SEO configuration to take advantage of new features like tabbed UI
• Update any custom components to work with the new plugin structure

General Updates

• Review relationship fields that use filterOptions as the behavior has been optimized
• Check upload fields for any issues after the upload-related fixes
• Test form submission emails if you're using that functionality

Upgrade Recommendations

Priority: Medium-High

This release contains significant improvements to the rich text editing experience and SEO plugin, along with numerous bug fixes that improve stability. The breaking changes are primarily isolated to the Lexical rich text editor.

Who should upgrade immediately:

• Projects using the SEO/meta plugin
• Applications with heavy rich text editing requirements
• Sites experiencing issues with relationship fields or upload handling

Who can wait:

• Projects not using the Lexical rich text editor or SEO plugin
• Applications with minimal content editing needs

Upgrade Steps:

1. Review the breaking changes, especially if using the Lexical rich text editor
2. Update both Payload and any @payloadcms/* packages together
3. Test thoroughly in a staging environment before deploying to production
4. Pay special attention to rich text content and SEO metadata after upgrading

The upgrade is recommended for most users as it brings significant improvements to content editing and developer experience, but those not using the affected features can upgrade at their convenience.

Bug Fixes

SEO Plugin Fixes

• Fixed meta length indicator
• Fixed meta image generation and upload field issues
• Fixed unnecessary pipe character in meta title (#33)
• Fixed payload config provider integration
• Fixed image field and type errors
• Fixed incorrect import paths in documentation

Rich Text Editor Fixes

• Fixed various type errors throughout the codebase
• Fixed issues with Lexical HTML field not working inside Blocks field
• Fixed problems with URL validation for different URL types
• Fixed unnecessary paragraph elements before upload, relationship and blocks nodes

Admin UI Fixes

• Added background color for year/month select options in datepicker
• Fixed cursor jumping issues inside JSON fields
• Fixed formatting of fields within tabs for list controls
• Fixed handling of empty arrays in getDataByPath
• Improved tab handling for better user experience

API and Data Handling

• Fixed issues with querying relationship fields
• Fixed handling of default values for fields with read access restrictions
• Fixed searching by ID which was sending undefined in where query parameters
• Fixed upload-related issues including cropping, fetching local files, and external preview images

New Features

SEO Plugin Improvements

• Renamed meta plugin to SEO for better clarity
• Refined SEO descriptions with improved auto-generation
• Added subsite inclusion in meta title generation
• Improved meta image generation and upload field handling
• Added error handling to meta title generation
• Added option for tabbed UI interface for better organization
• Added support for globals configuration

Rich Text Editor Enhancements

• Improved link URL validation in Lexical editor
• Enhanced floating select menu with better dropdown classNames
• Added support for generating URLs in SEO plugin
• Added dark-mode friendly colors

Admin Experience Improvements

• Added form submission emails functionality
• Added max file size labels to media fields
• Added new actions property to admin customization
• Improved admin navigation with smoother transitions

Developer Tools

• Added context property to auth and globals local API
• Added proper type exports for better TypeScript support
• Added support for passing locale through generateURL

Security Updates

No specific security fixes were mentioned in the release notes. The release focuses primarily on feature enhancements, bug fixes, and performance improvements rather than addressing security vulnerabilities.

Performance Improvements

Rich Text Editor Performance

• Lazy import of React components in Lexical editor to prevent client-only code from leaking into the server
• Improved handling of relationship fields by preventing unnecessary queries when filterOptions returns false

Database Optimizations

• Fixed PostgreSQL database issues with querying nested blocks fields
• Improved handling of MongoDB DocumentDB unique constraints
• Better handling of GraphQL schema generation for fields without queryable subfields

Admin UI Performance

• Smoother admin navigation transitions for better user experience
• Improved handling of uploads with better validation flow
• Optimized form field rendering and state management

Impact Summary

Payload CMS v2.5.0 delivers substantial improvements to the content editing experience, particularly through enhancements to the SEO plugin (formerly meta plugin) and the Lexical rich text editor. The release includes breaking changes to the Lexical editor that require code updates, but these are well-documented and primarily affect developers who have customized the editor.

The SEO plugin has been significantly improved with better meta description generation, title handling, and image support. Content editors will benefit from a more intuitive interface with the optional tabbed UI and better visual feedback for media uploads. Developers gain access to improved APIs, better TypeScript support, and more efficient relationship field handling.

Performance improvements include lazy loading of React components in the Lexical editor and optimized database queries. The admin UI experience has been enhanced with smoother navigation transitions and better form handling.

Overall, this release represents a solid step forward for Payload CMS with meaningful improvements for both developers and content editors. The breaking changes are limited in scope and the migration path is clear, making this a worthwhile upgrade for most users.

Full Release Notes

import { BlockIcon } from '../../lexical/ui/icons/Block'
...
Icon: BlockIcon,

// import { BlockIcon } from '../../lexical/ui/icons/Block' // <= Remove this import
...
Icon: () =>
  // @ts-expect-error
  import('../../lexical/ui/icons/Block').then((module) => module.BlockIcon),

// import BlockIcon from '../../lexical/ui/icons/Block' // <= Remove this import
...
Icon: () =>
  // @ts-expect-error
  import('../../lexical/ui/icons/Block'),