Payload CMS Release: 3.20.0

TL;DR

Payload CMS 3.20.0: Performance Boost & Enhanced Version Control

Payload CMS 3.20.0 brings significant performance improvements by optimizing field validations and introducing smarter form submission handling. The version comparison UI receives major enhancements with collapsible fields, customizable diff components, and the ability to show only modified fields. Other highlights include improved plugin stability, better localization publishing options, and numerous bug fixes across the admin UI and plugins.

Highlight of the Release

• Performance optimization by skipping field validations until form submission
• Enhanced version comparison UI with collapsible fields and option to show only modified fields
• Customizable version diff components through server-side configuration
• Option to set default locale publishing behavior (all locales or active locale only)
• Fixed field paths within hooks for more consistent behavior

Migration Guide

Upgrading to v3.20.0

No breaking changes are introduced in this release, making it a straightforward upgrade from previous v3.x versions.

For Custom Validation Functions

If you have custom validation functions that perform expensive operations (like database queries), consider updating them to use the new event parameter for better performance:

// Before
validate: async (value) => {
  // Expensive operation runs on every keystroke
  const result = await someExpensiveOperation(value)
  return result ? true : 'Invalid value'
}

// After
validate: async (value, { event }) => {
  if (event === 'onChange') {
    // Simple validation during typing
    return value ? true : 'Invalid value'
  }
  
  // Run expensive validation only on submit
  const result = await someExpensiveOperation(value)
  return result ? true : 'Invalid value'
}

For Localization Default Publish Option

If you want to change the default publish button behavior for localized content:

// In your Payload config
localization: {
  defaultLocalePublishOption: 'active', // 'active' or 'all' (default)
  locales: ['en', 'es', 'de'],
  // other localization options...
}

Upgrade Recommendations

This release is recommended for all users due to the significant performance improvements and bug fixes.

• Priority: Medium
• Complexity: Low (no breaking changes)
• Timing: Can be upgraded at your convenience

The performance optimizations around field validations will be particularly beneficial for forms with many fields or complex validation logic. Users of the Multi-Tenant, Nested Docs, or Form Builder plugins should definitely upgrade to resolve the fixed issues.

To upgrade, run:

npm install @payloadcms/[email protected]
# or
yarn add @payloadcms/[email protected]
# or
pnpm add @payloadcms/[email protected]

If you're using any official plugins, consider upgrading those as well to ensure compatibility.

Bug Fixes

Core Fixes

• Field Paths: Fixed inconsistencies in field paths within hooks, ensuring proper formatting without unnecessary index prefixes.
• Lexical Rich Text: Fixed issue where afterRead hooks were not being properly awaited, potentially causing glitches with uploads, relationships, and link nodes.
• UI Improvements:
  • Fixed blocksDrawer search state reset after closing
  • Added title attribute to Logout button for tooltip display
  • Fixed restore button's empty submenu in draft versions
  • Fixed tab subfield permissions not being correctly extracted

Plugin Fixes

• Multi-Tenant Plugin:
  • Now removes tenant cookie on logout
  • Fixed validation error "The following field is invalid: Assigned Tenant"
  • Prevents double redirect to globals when no tenant is selected
• Nested Docs Plugin:
  • Now properly updates both draft and published child documents when parent document is updated
• Form Builder Plugin:
  • Fixed type definitions for MessageField to be editor-agnostic

Other Fixes

• Fixed Estonian language support in translations
• Fixed Firefox selection preservation when using LexicalMenu
• Removed toString coercion inside getDocumentPermissions
• Fixed template issues with pnpm 10 compatibility

New Features

Enhanced Version Control UI

• Collapsible Fields in Version Diff: Fields like collapsible, group, array, blocks, and tabs can now be collapsed in the version comparison view, making it easier to navigate complex documents.
• Show Only Modified Fields: A new toggle allows users to focus only on fields that have changed between versions, reducing visual clutter.
• Customizable Diff Components: Developers can now customize version diff components through server-side configuration, including support for React Server Components.

Improved Localization Publishing

• Configurable Default Publish Option: Added defaultLocalePublishOption to localization config, allowing developers to set whether the primary publish button should publish all locales (default) or only the active locale.
• Better User Experience: This provides a more intuitive workflow for teams that primarily work with individual locales.

Enhanced Blank Template

• Added a simple front-end landing page to the Blank template, providing a better out-of-the-box experience when deploying to platforms like Payload Cloud or Vercel.
• The front-end is entirely optional and can be removed if not needed.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Optimized Field Validations

• Delayed Validation: Field validations now only run after form submission and on subsequent changes, rather than on every keystroke, significantly improving form responsiveness.
• Event-Based Validation: Added a new event argument to validation functions, allowing developers to implement different validation logic for onChange vs onSubmit events.
• Filter Option Validation: Relationship and upload fields now only validate filter options on form submission, avoiding expensive database lookups during typing.

Example of Performance-Optimized Validation

[
  {
    name: 'text',
    type: 'text',
    validate: async (value, { event }) => {
      if (event === 'onChange') {
        // Do something highly performant here
        return true
      }
      
      // Do something more expensive here (like DB queries)
      return true
    }
  }
]

This approach is particularly beneficial for fields with async validations or those performing database queries, such as relationship and upload fields with filter options.

Impact Summary

Payload CMS 3.20.0 delivers substantial improvements to both performance and user experience. The most impactful change is the optimization of field validations, which now only run on form submission rather than on every keystroke. This results in significantly faster form interactions, especially for forms with many fields or complex validation logic.

The version comparison UI receives major enhancements with collapsible fields and the ability to show only modified fields, making it much easier to review changes in complex documents. Developers also gain the ability to customize version diff components through server-side configuration.

For teams working with localized content, the new option to set a default locale publishing behavior (all locales or active locale only) provides more flexibility in content workflows.

Several important bug fixes address issues in plugins (Multi-Tenant, Nested Docs, Form Builder) and core functionality, including proper field path handling within hooks and improved Lexical rich text editor stability.

Overall, this release focuses on performance, user experience improvements, and bug fixes without introducing breaking changes, making it a recommended upgrade for all Payload users.

Full Release Notes