Payload CMS Release: 3.2.0

TL;DR

Payload CMS 3.2.0: Performance Boost and Enhanced Features

Payload CMS 3.2.0 brings significant performance improvements with up to 100x faster page navigation, new features like cross-locale data copying, and a JSX converter for Lexical rich text. The update also includes on-demand collection reindexing for search, improved RTL support, and various bug fixes that enhance the overall stability and user experience.

Highlight of the Release

• Up to 100x faster page navigation with optimized client configuration
• New ability to copy data across locales at document level
• On-demand collection reindexing for search functionality
• Lexical to JSX converter for rich text frontend rendering
• Improved RTL language support

Migration Guide

Migrating from react-animate-height

If you've been using react-animate-height in your custom components, you should consider migrating to the native CSS approach used in this release:

/* Add this to your CSS */
.your-animated-element {
  interpolate-size: allow-keywords;
  transition: height 0.2s ease-out;
}

// Replace this:
import AnimateHeight from 'react-animate-height';
<AnimateHeight height={isOpen ? 'auto' : 0}>
  {content}
</AnimateHeight>

// With this:
<div style={{ height: isOpen ? 'auto' : '0px' }}>
  {content}
</div>

Note that the CSS property interpolate-size: allow-keywords; is experimental, but the release includes a patch for browsers without native support.

Using the New Lexical to JSX Converter

To use the new Lexical to JSX converter in your frontend:

1. Import the necessary components:

import { RichText } from '@payloadcms/richtext-lexical/react'

2. Define your custom converters:

const jsxConverters = ({ defaultConverters }) => ({
  ...defaultConverters,
  // Add your custom converters here
})

3. Use the RichText component:

<RichText
  converters={jsxConverters}
  data={yourLexicalData}
/>

Upgrade Recommendations

This release brings significant performance improvements and useful new features without introducing breaking changes, making it a recommended upgrade for all Payload CMS users.

Priority: Medium-High

Who should upgrade immediately:

• Projects with large configurations experiencing slow admin panel navigation
• Multi-language sites that would benefit from the cross-locale content copying feature
• Projects using the search plugin that need to reindex collections
• Applications with RTL language support

Upgrade steps:

1. Update your Payload CMS dependency to version 3.2.0:

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

2. If you're using any of the plugins that received updates (form-builder, search, seo), update those as well to their latest compatible versions.

3. Test your application thoroughly, especially if you have custom components that might be affected by the changes to animation handling or rich text formatting.

Bug Fixes

UI and Accessibility Fixes

• Fixed localizer positioning in RTL mode, properly aligning it to the left side of the screen for RTL languages
• Removed overflow hidden from app-header wrappers, fixing issues with popout elements like dropdowns and menus
• Fixed SEO plugin fields not being properly disabled when a user lacks permissions

Rich Text Editor Fixes

• Prevented the use of text formats (bold, italic, etc.) when their features were not enabled in the editor configuration
• Fixed issues with text formatting being applied via keyboard shortcuts or paste operations even when the formatting features were disabled

Query and Access Control Fixes

• Fixed validation of where query paths from access results, resolving issues with findByID operations
• Properly threaded field permissions through version diffs, fixing display issues for iterable fields like blocks
• Added support for overriding entity visibility within drawers, allowing hidden entities to be rendered in document and list drawers
• Made emails non-unique when email login is disabled, providing more flexibility in user management

Other Fixes

• Fixed form builder plugin to allow overrides to payment fields group
• Fixed website template issues with loading lazy on medium hero components
• Corrected various TypeScript and null check issues

New Features

Copy Data Across Locales

A powerful new feature allows copying content from one locale to another at the document level. Content editors can now select origin and destination locales, with options to either overwrite existing data or only copy into empty fields in the destination locale.

On-Demand Collection Reindexing for Search

The search plugin now supports reindexing entire searchable collections on demand. This is particularly useful when adding the search plugin to an existing project with documents already in place. Users can select specific collections to reindex or choose to reindex all collections at once.

Lexical to JSX Converter

A new converter allows transforming Lexical rich text content into JSX for frontend rendering. This makes it easier to customize the display of rich text content in React applications:

import { RichText } from '@payloadcms/richtext-lexical/react'

const jsxConverters = ({ defaultConverters }) => ({
  ...defaultConverters,
  blocks: {
    myTextBlock: ({ node }) => <div style={{ backgroundColor: 'red' }}>{node.fields.text}</div>,
  },
})

export const MyComponent = ({ lexicalContent }) => {
  return (
    <RichText
      converters={jsxConverters}
      data={data.lexicalWithBlocks}
    />
  )
}

Exported hasText Helper

The hasText helper method has been extracted and exported from richTextValidateHOC, making it available for frontend serialization. This is useful for checking whether text content exists before rendering elements like captions.

Native CSS Animation

Deprecated the react-animate-height dependency in favor of native CSS animations using the interpolate-size: allow-keywords; property. This reduces bundle size while maintaining compatibility with the previous API.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Dramatically Faster Page Navigation

This release brings significant performance improvements to the admin panel, with page navigation speed increasing by up to 100x in some cases. The improvements come from several optimizations:

1. Faster Client Configuration: The createClientConfig function has been optimized, reducing execution time from seconds to milliseconds for large configurations. In test configurations with many fields and collections, execution time went from 4 seconds to just 50ms.

2. Proper Caching: Client configuration is now properly cached in both development and production environments, eliminating redundant processing between page navigations.

3. Optimized Version Fetching: Version queries have been optimized to use the select API for limiting queried fields and to skip database queries entirely when a document is published.

4. Faster Lexical Initialization: Removed unnecessary deep copying of Lexical objects, reducing memory usage and improving load times. The Lexical default config sanitization now happens less frequently.

These improvements are particularly noticeable for large configurations with many rich text fields, as the system no longer repeatedly deep-copies large editor configurations.

Impact Summary

Payload CMS 3.2.0 delivers a substantial performance boost to the admin panel with up to 100x faster page navigation through optimized client configuration and caching. Content editors gain powerful new tools like cross-locale content copying and on-demand collection reindexing for search functionality. Developers benefit from new features like the Lexical to JSX converter and the exported hasText helper for rich text validation.

The release also addresses several UI and accessibility improvements, including better RTL language support and fixes for dropdown menus in the app header. The migration from react-animate-height to native CSS animations reduces bundle size while maintaining compatibility.

Overall, this is a significant quality-of-life update that makes Payload CMS faster and more feature-rich without introducing breaking changes, making it a recommended upgrade for all users.

Full Release Notes