Payload CMS Release: 2.13.0

TL;DR

Payload CMS v2.13.0 introduces custom database table and enum names, JSON field schemas, and a new Horizontal Rule feature for the rich text editor. This release also includes significant improvements to database queries across MongoDB and PostgreSQL adapters, fixes for relationship handling, and enhanced error handling. A breaking change affects sub-richtext fields within Lexical, requiring the editor prop to be specified.

Highlight of the Release

• Custom database table and enum names for better integration with existing systems
• New JSON field schemas for structured data validation
• Horizontal Rule feature added to the rich text editor
• Improved database query handling for relationships across MongoDB and PostgreSQL
• Enhanced error handling and validation for login operations
• Fixed issues with document duplication and draft handling

Migration Guide

Breaking Change: Sub-richtext Fields in Lexical

This release modifies field types which are allowed to be passed in to upload, link, and blocks lexical features. This can break your types even if no sub-richText editor is passed in.

If you're using sub-richtext fields within Lexical defined in your Payload config, you now need to explicitly specify the editor prop. Previously, omitting this prop was allowed, but it's now required for type safety and consistency.

Example of the required change:

// Before
{
  name: 'content',
  type: 'richText',
  // No editor specified
}

// After
{
  name: 'content',
  type: 'richText',
  editor: lexicalEditor({
    // your editor config
  })
}

Make sure to update all instances where you have sub-richtext fields within Lexical features like uploads, links, and blocks.

Upgrade Recommendations

This release contains important bug fixes and new features that benefit most Payload CMS users. The upgrade is recommended for all users, with special attention needed for those using sub-richtext fields within Lexical.

Who should upgrade immediately:

• Users experiencing issues with relationship queries in PostgreSQL
• Anyone having problems with document duplication
• Users who need the new custom database table naming features
• Projects using localized content with relationship fields

Before upgrading:

1. Review the breaking change regarding sub-richtext fields in Lexical
2. Test the upgrade in a non-production environment first
3. Update any code that might be affected by the breaking change

How to upgrade:

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

After upgrading, test your application thoroughly, especially if you're using rich text fields with Lexical editor.

Bug Fixes

Database Fixes

MongoDB

• Fixed failing contains query with special characters
• Fixed version fields indexSortableFields
• Improved error handling by ignoring end session errors

PostgreSQL

• Fixed issues with hasMany relationship queries containing operators
• Resolved problems with localized relationship queries not respecting locale constraints
• Fixed relationship query pagination
• Fixed validateExistingBlockIsIdentical for localized content

Rich Text Editor Fixes

• Added error catching during HTML generation to prevent crashes
• Fixed incorrect floating handle y-position calculation next to certain HTML elements like HR
• Limited unnecessary floating handle positioning updates
• Fixed schema generation by passing through config properly
• Ensured correct nodeType on HorizontalRule feature HTML converter

General Fixes

• Fixed issue with duplicate document creation when attempting multiple times in quick succession
• Resolved missing date locales
• Fixed number IDs not being sanitized to number in REST API
• Fixed req.collection being lost when querying a global inside a collection
• Fixed block field type missing dbName
• Improved handling of drafts in bulk update operations
• Fixed issue with document preferences when creating new documents
• Updated type name of CustomPublishButtonProps to CustomPublishButtonType with backward compatibility
• Added type error validations for email and password in login operation
• Fixed parent ID handling in saveVersion

New Features

Custom Database Table and Enum Names

You can now customize database table and enum names, allowing for better integration with existing systems and more control over your database structure. This is particularly useful when migrating from other systems or when you need to follow specific naming conventions.

JSON Field Schemas

The new JSON field schemas feature provides structured data validation for JSON fields, making it easier to ensure data integrity and consistency in your content models.

Rich Text Editor Improvements

• Horizontal Rule Feature: Added a new Horizontal Rule feature to the Lexical rich text editor, allowing content editors to insert horizontal dividers in their content.
• Improved Floating Handle Positioning: The rich text editor now has better positioning for floating handles, especially for smaller elements, providing a more intuitive editing experience.

External File Headers Configuration

You can now configure headers for external file fetches, providing more control over security and integration with external file storage systems.

Internationalization Enhancements

• Added Chinese translation for the SEO plugin
• Added Ukrainian translation for the SEO plugin

Security Updates

No specific security fixes were mentioned in this release. However, the addition of configuration for setting headers on external file fetches could improve security by allowing better control over external resource access.

Performance Improvements

Query Performance Improvements

• Improved relationship query handling in PostgreSQL, which should result in better performance for complex queries involving relationships
• Enhanced handling of hasMany fields with 'in' operator in PostgreSQL
• Optimized handling of localized relationships in database queries

Rich Text Editor Performance

• Limited unnecessary floating handle positioning updates in the rich text editor, reducing DOM operations
• Improved HTML generation with better error handling to prevent performance issues

Document Creation Performance

• Avoided getting and setting document preferences when creating new documents, streamlining the creation process

Impact Summary

Payload CMS 2.13.0 delivers significant improvements to database handling, particularly for relationship queries in both MongoDB and PostgreSQL adapters. The addition of custom database table and enum names provides developers with more flexibility when integrating with existing systems or following specific naming conventions.

The rich text editor receives notable enhancements with the new Horizontal Rule feature and improved floating handle positioning, making content editing more intuitive. JSON field schemas add structured data validation capabilities, improving data integrity across your content models.

This release includes one breaking change affecting sub-richtext fields within Lexical, requiring the editor prop to be explicitly specified. While this improves type safety, it may require code updates in projects using these features.

The numerous bug fixes address issues with document duplication, localization, relationship queries, and draft handling, making this a solid maintenance release that improves stability across the board. The addition of Ukrainian and Chinese translations for the SEO plugin also enhances the CMS's internationalization support.

Overall, this release balances new features with important bug fixes and performance improvements, making it a recommended upgrade for most Payload CMS users.

Full Release Notes