Payload CMS Release: Release v2.3.0

TL;DR

Payload CMS v2.3.0 introduces several new features including support for JavaScript migrations, OAuth 2.0 Bearer tokens, Serbian translations, and a new useDocumentEvents hook. The release also includes significant improvements to the relationship field with sortable options, intelligent migration directory searching for MongoDB and PostgreSQL, and batched API requests for Live Preview. Multiple bug fixes address issues with rich text editors, PostgreSQL database operations, and Live Preview functionality. This update enhances developer experience while maintaining backward compatibility except for some breaking changes to the Lexical rich text editor's slash menu components.

Highlight of the Release

• Support for JavaScript migration files alongside TypeScript
• OAuth 2.0 Bearer token support in Authorization headers
• New useDocumentEvents hook for real-time document updates
• Serbian language translations (Latin and Cyrillic)
• Relationship fields now support sortable options
• Improved Live Preview with batched API requests and better relationship handling
• Fixed PostgreSQL issues with nested arrays and block field queries

Migration Guide

Breaking Changes in @payloadcms/richtext-lexical

If you're using custom Lexical Features that add new slash menu entries, you'll need to update your code:

1. SlashMenuOption Changes:

   • The first argument is now used as a key and not as a display name
   • Add an optional displayName property for the display name
   • Ensure your key doesn't contain spaces or special characters

2. SlashMenuGroup Changes:

   • The title property has been replaced with a mandatory key property
   • Add an optional displayName property if needed
   • Ensure your key doesn't contain spaces or special characters

3. CSS Classes:

   • If you have custom styles targeting elements inside slash or floating-select-toolbar menus, you'll need to adjust them as the CSS classes have changed

Example of these updates can be found in this pull request.

If you're not using custom Lexical Features with slash menu entries, no action is required.

Upgrade Recommendations

Who should upgrade?

• All users should consider upgrading to benefit from bug fixes and new features
• Users of Live Preview will see significant improvements in performance and reliability
• Users with Serbian content editors will benefit from the new language support
• Developers using migrations will appreciate the new JavaScript file support
• Projects using PostgreSQL should upgrade to fix critical database operation issues

Upgrade Priority: Medium-High

This release contains valuable features and important bug fixes without major breaking changes for most users. The only breaking changes affect developers who have created custom Lexical rich text editor slash menu components.

How to upgrade:

1. Update your dependencies:

   npm install @payloadcms/[email protected]
   # or
   yarn add @payloadcms/[email protected]
   # or
   pnpm add @payloadcms/[email protected]
   

2. If you're using the Lexical rich text editor with custom slash menu components, review the migration guide for necessary changes.

3. Test your application thoroughly, especially if you're using PostgreSQL, rich text editors in tabs, or Live Preview functionality.

Bug Fixes

Rich Text Editors

• Lexical Rich Text Editor:
  • Fixed HTML Converter field not working inside of tabs
  • Re-used Payload population logic to fix various population-related issues
• Slate Rich Text Editor:
  • Added 'use client' directive to top of TSX files importing from Payload core, fixing React Server Component compatibility

Database Operations

• PostgreSQL:
  • Fixed error when saving nested arrays with versions
  • Fixed issue with querying nested block fields
  • Resolved issues with duplicate documents containing required localized fields

UI Components

• Tabs Component: Fixed incorrect key property in Tabs field component (issue #4282)
• Fixed proper setting of tabs key in fieldSchemaToJSON

Live Preview

• Compound Fields: Fixed issue with compound fields not properly merging results
• Rich Text Nodes: Fixed property resets for rich text editor nodes
• Dependencies: Removed Payload from peer dependencies in both live-preview and live-preview-react packages
• Relationship Updates: Fixed re-population of externally updated relationships

Other Fixes

• Fixed export of useDocumentsEvents hook
• Fixed duplication of documents with required localized fields

New Features

Core Functionality

• JavaScript Migration Support: Added support for JavaScript migration files alongside TypeScript files, making migrations more flexible and accessible to developers who prefer JavaScript.
• OAuth 2.0 Bearer Tokens: Added support for the standard OAuth 2.0 format Authorization: Bearer tokens in headers, improving authentication compatibility with other systems.
• useDocumentEvents Hook: New React hook that allows developers to subscribe to real-time document updates.
• Serbian Language Support: Added translations for Serbian in both Latin and Cyrillic scripts, expanding internationalization capabilities.

Field Enhancements

• Relationship Field Improvements: Added sortOptions property to relationship fields, allowing developers to define how relationship options are sorted in the admin UI.

Database Adapters

• Intelligent Migration Directory Search: Both MongoDB and PostgreSQL adapters now intelligently search for migration directories, making the setup process more intuitive.

Live Preview

• Batched API Requests: Live Preview now batches API requests, reducing network traffic and improving performance.
• Improved Relationship Handling: Live Preview now properly re-populates externally updated relationships, ensuring accurate previews.

Security Updates

No specific security fixes were mentioned in this release. However, the addition of OAuth 2.0 Bearer token support improves authentication standards compliance, which indirectly contributes to better security practices.

Performance Improvements

Live Preview

• Batched API Requests: The Live Preview feature now batches API requests together, significantly reducing the number of network calls made during editing sessions. This results in smoother preview experiences, especially when working with complex documents that have many relationships or nested fields.

Rich Text Editors

• Population Logic: The Lexical rich text editor now re-uses Payload's core population logic instead of implementing its own, which not only fixes bugs but also improves consistency and performance when working with populated relationships within rich text content.

Database Operations

• Intelligent Migration Directory Search: Both MongoDB and PostgreSQL adapters now search for migration directories more intelligently, reducing setup time and improving the developer experience when working with database migrations.

Impact Summary

Payload CMS 2.3.0 delivers a substantial update focused on developer experience, internationalization, and database reliability. The addition of JavaScript migration support alongside TypeScript provides more flexibility for development teams with varied preferences. The new useDocumentEvents hook enables real-time document updates, which can significantly enhance interactive applications built with Payload.

For international teams, the addition of Serbian language support (in both Latin and Cyrillic scripts) continues Payload's commitment to global accessibility. Database administrators will appreciate the intelligent migration directory searching in both MongoDB and PostgreSQL adapters, simplifying setup and maintenance.

Content editors benefit from numerous fixes to the rich text editors and Live Preview functionality. The batched API requests in Live Preview and improved relationship handling make the editing experience smoother and more reliable, especially for complex content structures.

The only notable breaking change affects developers who have created custom Lexical rich text editor slash menu components, requiring updates to their implementation. For most users, this update is a straightforward improvement with minimal migration effort required.

Overall, this release strengthens Payload's position as a flexible, developer-friendly CMS while addressing key pain points in database operations and content editing workflows.

Full Release Notes