Payload CMS Release: 3.27.0

TL;DR

Payload CMS v3.27.0 introduces several significant features including a new admin bar, import/export plugin, compound indexes, and field path threading in conditions. It also includes important bug fixes for authentication, field validation, and storage handling. This release enhances developer experience with better error messages and configuration options while improving overall system reliability.

Highlight of the Release

• New PayloadAdminBar component for easier content editing
• Import/Export plugin for downloading and uploading collection data
• Compound indexes support for improved database performance and data integrity
• Field condition functions now receive path information
• Option to disable blockName field in blocks' headers
• Improved field error toast messages for better readability

Migration Guide

Migrating from payload-admin-bar to @payloadcms/admin-bar

If you were using the standalone payload-admin-bar package, you'll need to update your imports and prop names:

- import { PayloadAdminBar } from 'payload-admin-bar'
+ import { PayloadAdminBar } from '@payloadcms/admin-bar'

<PayloadAdminBar
-  collection="pages"
+  collectionSlug="pages"
-  authCollection="users"
+  authCollectionSlug="users"
  // other props remain the same
/>

GCS Storage Client Uploads

If you're using the GCS storage adapter with client uploads, ensure you have explicitly set the clientUploads property, as the previous behavior incorrectly used enabled instead:

{
  gcsStorageOptions: {
    clientUploads: true, // Make sure this is explicitly set
    // other options...
  }
}

Also remember that to enable client uploads with GCS, you need to configure CORS on Google Cloud.

Upgrade Recommendations

This release contains several important bug fixes and new features that enhance Payload's functionality. We recommend upgrading to v3.27.0, especially if you:

1. Need better database performance through compound indexes
2. Want to use the new import/export functionality
3. Are experiencing issues with authentication strategies, field validation, or client uploads
4. Need more control over block field rendering in the admin UI

The upgrade should be straightforward for most users, with special attention needed only if you're using the GCS storage adapter with client uploads or the standalone admin bar package.

Before upgrading, review the migration guide for specific changes that might affect your implementation, particularly if you're using the payload-admin-bar package which has been moved into the monorepo as @payloadcms/admin-bar.

Bug Fixes

Authentication and Access Control

• Fixed safe auth strategy execution to prevent admin panel loading failures when authentication strategies encounter errors
• Fixed an issue where beforeValidate was deleting values when access control returned false
• Corrected client uploads with disablePayloadAccessControl: true to ensure proper functionality

UI and Rendering

• Fixed views rendered in drawers updating the step nav incorrectly
• Ensured client upload handler only executes when a file exists
• Fixed admin panel compilation failures when fullySpecified is set in Next.js config
• Fixed bug in Lexical rich text editor's $createAutoLinkNode when links are preceded by text nodes

Configuration and Data Handling

• Fixed collection config deep merge during sanitization that was causing unpredictable behavior and performance issues
• Corrected the formatting of admin URLs inside forgot password emails
• Fixed GCS storage client uploads being enabled even when clientUploads was not explicitly set
• Fixed issues with indexes not being iterable during default value sanitization

New Features

PayloadAdminBar Component

The payload-admin-bar package has been imported into the Payload monorepo as @payloadcms/admin-bar. This component provides an easy way to add admin controls to your frontend, allowing content editors to quickly access editing functionality. The package is now maintained alongside other Payload packages and includes its own test suite.

Import/Export Plugin

A new plugin has been added that allows for direct download and creation of downloadable collection data stored in JSON or CSV formats. The plugin respects the access control of the user creating the request. Configuration options include:

• Specifying collections to include in the Import/Export controls
• Disabling the jobs queue to run exports synchronously
• Overriding the export collection configuration

Compound Indexes

Collections can now define indexes on multiple fields (compound indexes). This can be used to either speed up querying/sorting by two or more fields simultaneously or to ensure uniqueness across several fields.

{
  indexes: [{ unique: true, fields: ['title', 'group.name'] }]
}

Field Path in Condition Functions

Field condition functions now receive a path argument that provides the schema path of the field, including array indices where applicable. This allows for more precise conditional logic based on the field's location in the document structure.

Import Map Location Override

A new importMapFile property allows overriding the default import map location, providing more flexibility in project structure. Previously, Payload only looked for import maps in specific locations.

Disable Block Name Field

Added a new admin.disableBlockName property that allows hiding the blockName field in blocks' headers in the admin view, creating a cleaner interface when block naming isn't needed.

Security Updates

No specific security fixes were mentioned in this release. The changes related to authentication strategies and access control were primarily focused on functionality rather than addressing security vulnerabilities.

Performance Improvements

Collection Config Handling

The PR #11524 introduced reliable merge functions that are faster and ensure no object references are shared with defaults that reside in the module scope. This addresses performance issues with the previous deep-merging approach during collection config sanitization, which was not only slow but could lead to unpredictable behavior.

Compound Indexes

The new compound indexes feature (#11512) allows for more efficient database queries when filtering or sorting by multiple fields simultaneously. This can significantly improve performance for complex queries that previously would have required scanning more documents.

MongoDB Image Caching

Added caching of MongoDB images in CI to avoid rate limiting issues, which improves the reliability and speed of the CI pipeline.

Impact Summary

Payload CMS v3.27.0 delivers significant enhancements to both developer experience and content management capabilities. The introduction of compound indexes addresses a long-standing need for more sophisticated database optimization, while the new import/export plugin simplifies data management workflows.

The PayloadAdminBar component, now officially part of the Payload ecosystem, provides a seamless way to integrate admin controls into frontend applications, improving content editor workflows. Developers will appreciate the more predictable behavior in collection configuration handling and the additional flexibility provided by features like path information in field conditions and customizable import map locations.

Several critical bug fixes improve the reliability of authentication, field validation, and storage handling, particularly for projects using client uploads or custom access control settings. The UI improvements, including better error messages and drawer handling, contribute to a more polished admin experience.

Overall, this release balances new capabilities with important refinements to existing functionality, making it a worthwhile upgrade for most Payload projects.

Full Release Notes