Payload CMS Release: 2.18.0

TL;DR

PayloadCMS 2.18.0 brings focal point storage for uploads and critical bug fixes

This release adds the ability to store focal point data on uploads, making image cropping and responsive layouts more powerful. It also fixes important bugs in PostgreSQL filtering and the Lexical rich text editor. These improvements enhance both developer experience and content management capabilities for PayloadCMS users.

Highlight of the Release

• Added focal point storage for uploads with focalX and focalY properties
• Fixed PostgreSQL filtering issue with ID not_in operator in AND queries
• Fixed reliability issues with node insertion in the Lexical rich text editor

Migration Guide

No migration is required for this release. The focal point data will be automatically stored on uploads when users set focal points through the admin UI. Existing uploads will not have focal point data until it is explicitly set.

For developers who want to leverage the new focal point data:

1. Access the focalX and focalY properties on your upload documents
2. These values represent the coordinates of the focal point as decimal values between 0 and 1
3. Use these values in your frontend code to dynamically crop or position images

Example usage in a frontend component:

const imageStyle = {
  objectPosition: `${upload.focalX * 100}% ${upload.focalY * 100}%`,
  objectFit: 'cover'
};

return <img src={upload.url} style={imageStyle} alt={upload.alt} />;

Upgrade Recommendations

This release is recommended for all PayloadCMS users, especially those who:

1. Use PostgreSQL as their database and rely on complex filtering operations
2. Work extensively with the Lexical rich text editor and frequently insert uploads, relationships, or blocks
3. Need better control over how images are displayed across different devices and layouts

The upgrade should be straightforward with no breaking changes. Update your PayloadCMS dependency to version 2.18.0:

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

Bug Fixes

PostgreSQL Filtering Fix

Fixed an issue with PostgreSQL where filtering by two queries with AND, if the first query involved ID and the not_in operator, would prevent the second query from being evaluated. This bug (issue #5151) was causing incorrect filtering results in PostgreSQL databases, potentially affecting data retrieval operations throughout applications using this database engine.

Rich Text Editor Improvements

Fixed reliability issues in the Lexical rich text editor where upload, relationship, and block node insertion would sometimes fail. This backported fix from PR #6389 ensures more consistent editing experiences when working with complex content that includes media, relationships to other documents, or nested block structures.

New Features

Focal Point Storage for Uploads

PayloadCMS now stores focal point data on uploads as focalX and focalY properties. This feature allows content creators to specify the most important part of an image, which can be used to create more intelligent cropping and responsive layouts.

When uploading or editing images, users can set a focal point that will be preserved in the upload document. Developers can then use this data to ensure that the most important part of an image remains visible regardless of how it's cropped or displayed across different devices and screen sizes.

This enhancement addresses a long-standing community request (Discussion #4082) and provides a foundation for more advanced image handling capabilities.

Security Updates

No specific security fixes were included in this release.

Performance Improvements

Query Performance Improvements

The fix for PostgreSQL filtering with ID and not_in operators in AND queries indirectly improves query performance by ensuring that all conditions are properly evaluated. This prevents unnecessary database operations that might occur when filtering conditions are incorrectly processed, leading to more efficient data retrieval for complex queries.

Impact Summary

PayloadCMS 2.18.0 delivers meaningful improvements to both content management and developer experience. The addition of focal point storage for uploads addresses a long-requested feature that enhances image handling capabilities, giving content creators more control over how their visual assets are displayed across different contexts.

The bug fixes for PostgreSQL filtering and the Lexical rich text editor resolve important issues that could affect data retrieval accuracy and content editing reliability. The PostgreSQL fix ensures that complex queries with ID and not_in operators work as expected, which is crucial for applications that rely on precise filtering. The improvements to the rich text editor make the content creation experience more stable when working with media and relationships.

Overall, this release strengthens PayloadCMS's capabilities as a robust content management system while addressing specific pain points reported by the community. The changes are non-breaking and provide immediate benefits without requiring migration efforts.

Full Release Notes