Payload CMS Release: 3.22.0

TL;DR

Payload CMS v3.22.0 brings significant UI improvements, including enhanced TextField UX for hasMany fields and locale filtering capabilities. This release also fixes several critical bugs in relationship filters, Postgres database handling, and rich text editor functionality. The update focuses on improving user experience, fixing data handling issues, and enhancing developer tooling with better test suites and TypeScript support.

Highlight of the Release

• Enhanced TextField UX for hasMany fields with inline editing
• New locale filtering capabilities with custom logic support
• Fixed critical Postgres database issues with select fields and globals
• Improved relationship filtering experience in the admin UI
• Better document data access for rich text editor sub-fields

Migration Guide

Migrating to v3.22.0

For Rich Text Editor Users

If you were previously relying on the data property in lexical sub-fields to access block-level data, you should now use the new blockData property instead. The data property now correctly contains the top-level document data in all contexts.

// Before
{
  name: 'myField',
  type: 'text',
  // data here incorrectly contained block-level data
  validate: (value, { data }) => {
    if (data.someBlockProperty) {
      // ...
    }
    return true;
  }
}

// After
{
  name: 'myField',
  type: 'text',
  // data now contains top-level document data
  // blockData contains the parent block data
  validate: (value, { data, blockData }) => {
    if (blockData.someBlockProperty) {
      // ...
    }
    return true;
  }
}

This change affects field conditions, read/update/create field access control, validation, and filterOptions for all fields within lexical blocks/links/upload.

For JSDocs Generation

If you were using function-based descriptions that relied on dynamic content, be aware that these functions are no longer evaluated for JSDocs generation in TypeScript types.

Upgrade Recommendations

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

• Use Postgres as their database (critical fixes for select fields and globals)
• Work with rich text editor and nested fields
• Rely on relationship filters in the admin UI
• Need better localization control in multi-tenant applications

The upgrade should be straightforward with minimal breaking changes. The main consideration is for developers who were relying on the incorrect behavior of the data property in lexical sub-fields, who should now use the new blockData property instead.

To upgrade:

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

After upgrading, test your application thoroughly, especially if you're using any of the features that received significant updates in this release.

Bug Fixes

Database Fixes

• Postgres Select Fields: Fixed issue where select fields with hasMany: true didn't save properly during autosave operations
• Postgres Globals: Ensured globals have proper createdAt, updatedAt, and globalType fields consistent with other database adapters

UI and Filtering Improvements

• Relationship Filters: Fixed multiple issues with relationship filters in the list view:
  • Prevented filter values from clearing on blur
  • Fixed stale queries remaining after clearing values
  • Resolved issue where removing the final condition would close the entire where builder
• Schedule Publish: Fixed issue preventing access to schedule publish functionality when a document had already been published without changes
• Image Components: Applied cacheTags upload config property consistently across all admin panel image components

Rich Text Editor Fixes

• Document Data Access: Ensured sub-fields have access to full document data in form state
• Block Data Access: Added new blockData property to access parent block data in lexical fields
• Validation: Fixed duplicative error paths in validation
• Modified-Only Diff View: Fixed error when viewing modified-only diff view containing localized arrays

Multi-tenant Plugin Fixes

• Fixed issue where document default value was incorrectly set on load when navigating from list view with no tenant selected

New Features

Enhanced TextField UX for hasMany Fields

The UX for TextField components with hasMany: true has been significantly improved by:

• Removing the dropdown menu and its indicator
• Removing the ClearIndicator that could cause accidental data loss
• Making text items directly editable inline instead of requiring removal and re-addition

Locale Filtering Configuration

A new filterAvailableLocales configuration option allows developers to determine which locales should be available per request. This enables:

• Customizing visible locales in the localizer selection menu
• Scoping locales to specific users or tenants
• Implementing dynamic locale availability based on custom logic

Example implementation:

localization: {
  defaultLocale: 'en',
  locales: ['en', 'es'],
  filterAvailableLocales: async ({ req, locales }) => {
    // Custom logic to filter available locales
    // Return filtered locales array
  },
}

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Improved React Hooks

The useIgnoredEffect hook has been significantly improved to enhance performance and reliability:

• Fixed issue where the effect didn't receive updated values of ignoredDeps, causing stale values
• Improved object comparison by using reference instead of value comparison, which is faster and more consistent with React's useEffect
• Fixed edge cases where the effect would not run even when dependencies changed
• Implemented a new pattern combining useEffect with a polyfilled useEffectEvent hook for better separation of reactive and non-reactive logic

Developer Tooling Improvements

• Added TypeScript strict mode to improve type safety and performance
• Improved test suite organization and reduced flakiness in tests
• Enhanced port handling in development to automatically find available ports

Impact Summary

Payload CMS v3.22.0 delivers significant improvements to the user experience and developer tooling. Content editors will benefit from enhanced text field interactions, better relationship filtering, and more intuitive locale management. Developers gain critical fixes for Postgres database handling, improved rich text editor functionality, and better TypeScript support.

The most impactful changes include:

1. Improved inline editing for text fields with hasMany: true
2. New locale filtering capabilities that enable tenant-specific localization
3. Fixed Postgres database issues with select fields and globals
4. Enhanced relationship filtering in the admin UI
5. Better document data access for rich text editor sub-fields

This release represents a solid improvement in both user experience and technical stability, with minimal migration effort required. The only notable change requiring attention is the new blockData property for accessing parent block data in lexical fields, which replaces the previous (incorrect) behavior of the data property in these contexts.

Full Release Notes