Payload CMS Release: 3.1.1

TL;DR

Payload CMS v3.1.1 is a maintenance release that brings significant performance improvements, bug fixes, and template optimizations. It focuses on enhancing query performance, fixing UI issues, improving template functionality, and addressing various bugs across the system. This release is particularly beneficial for users experiencing performance bottlenecks with complex queries or large collections.

Highlight of the Release

• Significant performance improvements with new flattenedFields collection/global property and removal of deep copying in validateQueryPaths
• Website template optimizations for image sizes and loading
• Fixed issues with the DatePicker, react-select menu z-index, and list preferences
• Fixed MongoDB relationship handling with named tabs within tabs
• Added support for Slovenian language and improved Russian translations

Migration Guide

Public Directory Location Change

The location of the public directory has changed. If you're upgrading from a previous version, you'll need to update your configuration to reflect this change.

No other breaking changes were mentioned that would require migration steps.

Upgrade Recommendations

This is a maintenance release with significant performance improvements and bug fixes. It's recommended for all users to upgrade, especially if you:

1. Experience performance issues with complex queries or large collections
2. Use the website templates and want improved image loading and performance
3. Have encountered any of the specific bugs fixed in this release, such as DatePicker locale issues or list preference problems
4. Use MongoDB with complex field structures including nested tabs
5. Need support for Slovenian language

The upgrade should be straightforward as there are no breaking changes mentioned, except for the public directory location change which is documented in the migration guide.

Bug Fixes

UI Fixes

• Fixed incorrect locale registration in DatePicker that was causing console errors
• Fixed CSS misalignment of icons inside date picker field
• Fixed z-index issues on react-select menu to ensure proper stacking context
• Fixed column reset issues when sorting in the admin UI
• Fixed improper spread of list preferences that was causing preferences to save incorrectly

Database Fixes

• Fixed MongoDB sanitizeRelationshipIDs to work properly with named tabs within tabs
• Fixed Postgres select fields with hasMany: true to allow clearing by passing an empty array
• Fixed migrations sorting in getMigrations to ensure consistent execution order
• Fixed race condition in async operations by properly isolating transaction IDs

Template Fixes

• Fixed Firefox logo display issues in website template
• Fixed image loading issues when hosting with Vercel
• Fixed imports in website template from @payloadcms/ui to be direct
• Fixed Vercel website template payload config regression

Other Fixes

• Fixed /payload-jobs/run endpoint to work without workflows
• Ensured deleteJobOnComplete property for jobs works properly
• Added Slovenian ('sl') to accepted languages
• Fixed custom anchor tags in docs with duplicate headings

New Features

Website Template Performance Improvements

The website template has received significant performance optimizations:

• Added pagination: false where totalDocs is not needed
• Implemented depth: 0 and selective field fetching in preview routes
• Added select to retrieve only needed properties in search functionality
• Implemented type safety best practices with defaultPopulate
• Now uses payload.count to resolve SSG pageNumbers

Website Template Image Optimizations

• Added defaultPopulate on pages and posts
• Further optimized images and fetching of staticParams

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Query Performance Improvements

A significant performance enhancement has been implemented with the addition of the flattenedFields property for sanitized collection/global configs. This property contains fields in database schema structure, which:

• Removes rows, collapsible, and unnamed tabs and merges them to the parent fields
• Ignores UI fields
• Adds named tabs as type: 'tab'

This simplifies code in places like Drizzle transform/traverseFields and avoids calling flattenTopLevelFields, reducing overhead.

Additionally, deep copying has been removed from validateQueryPaths, which significantly improves performance for each where query constraint. This is particularly impactful for large collection/global configs or when using Lexical with blocks.

Benchmark results showed impressive improvements:

• Before: Total execution time of ~24,657ms for test queries
• After: Total execution time of ~17,818ms for test queries

This represents approximately a 28% performance improvement for complex queries.

Impact Summary

Payload CMS v3.1.1 delivers substantial performance improvements that will benefit users with complex queries or large data structures. The addition of the flattenedFields property and removal of deep copying in query validation can result in up to 28% faster query performance in benchmark tests.

The release also addresses several UI issues that improve the admin experience, particularly with DatePicker locale handling, react-select menu z-index, and list preference saving. These fixes enhance the overall usability and reliability of the admin interface.

For template users, the website template optimizations for image sizes and loading will result in better performance and user experience. The fixes for Firefox logo display and Vercel image loading ensure broader compatibility.

Database-specific fixes for both MongoDB and Postgres improve reliability when working with complex field structures and relationship handling. The migration sorting fix ensures more consistent and reliable migrations.

Overall, this release represents a solid maintenance update that improves performance, fixes bugs, and enhances the developer and content editor experience without introducing breaking changes.

Full Release Notes