Payload CMS Release: 3.24.0

TL;DR

Payload CMS v3.24.0 brings significant performance improvements, new features like route transitions and block references, and numerous bug fixes. This release focuses on enhancing developer experience with better TypeScript support, optimizing permissions calculations, and improving UI components. Key highlights include the ability to deduplicate blocks across collections, join fields across multiple collections, and a new confirmation modal component for standardized user interactions.

Highlight of the Release

• New config.blocks property allows deduplicating blocks used in multiple places, significantly improving performance
• Route transitions provide visual feedback during page navigation with a progress bar
• Join fields can now query across multiple collections with the new array syntax for collection
• Standardized confirmation modal component for consistent user interactions
• Significant performance improvements for permissions calculations with lots of blocks
• New siblingFields argument in field hooks for easier access to related field data
• Better TypeScript support with improved view component types

Migration Guide

Route Transitions

If you want to use the new route transitions feature, you'll need to replace Next.js Link components with Payload's Link component:

- import { Link } from 'next/link'
+ import { Link } from '@payloadcms/ui'

For programmatic navigation, wrap your router calls with the startRouteTransition method:

import { useTransition } from '@payloadcms/ui'
import { useRouter } from 'next/navigation'

const MyComponent = () => {
  const router = useRouter()
  const { startRouteTransition } = useRouteTransition()
 
  const redirectSomewhere = useCallback(() => {
    startRouteTransition(() => router.push('/somewhere'))
  }, [startRouteTransition, router])
  
  // ...
}

Block References

To use the new block references feature, define your blocks in the blocks array of your Payload Config:

import { buildConfig } from 'payload'

const config = buildConfig({
  // Define blocks once
  blocks: [
    {
      slug: 'TextBlock',
      fields: [
        {
          name: 'text',
          type: 'text',
        },
      ],
    },
  ],
  collections: [
    {
      slug: 'collection1',
      fields: [
        {
          name: 'content',
          type: 'blocks',
          // Reference blocks by slug
          blockReferences: ['TextBlock'],
          blocks: [], // Required to be empty for compatibility
        },
      ],
    },
  ],
})

Note that you must keep the blocks array empty when using blockReferences for compatibility reasons.

Confirmation Modal

If you've implemented custom confirmation modals throughout your admin UI, consider migrating to the new standardized ConfirmationModal component:

import { ConfirmationModal, useModal } from '@payloadcms/ui'

// Define a unique modal slug
const modalSlug = 'my-confirmation-modal'

// In your component
const { openModal } = useModal()

// Open the modal
openModal(modalSlug)

// Render the modal component
<ConfirmationModal
  heading="Are you sure?"
  body="Confirm or cancel before proceeding."
  modalSlug={modalSlug}
  onConfirm={() => {
    // Your confirmation logic
  }}
/>

Upgrade Recommendations

This release contains significant performance improvements and bug fixes, making it a recommended upgrade for all Payload users. The introduction of block references can dramatically improve performance for projects with many duplicated blocks.

Who should upgrade immediately:

• Projects with large Payload configs that define the same blocks in multiple places
• Applications experiencing performance issues with permissions calculations
• Projects using PostgreSQL with complex queries involving table joins
• Anyone experiencing issues with autosave or document locking
• Sites with content editors in Pacific timezones using date fields

Upgrade steps:

1. Update your Payload dependencies:

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

2. If you're using the rich text editor, ensure you have the correct Lexical version:

   npm install [email protected]
   # or equivalent with yarn/pnpm
   

3. Test your application thoroughly, especially if you're using features that received significant updates like blocks, joins, or autosave functionality.

The upgrade should be straightforward for most users as there are no breaking changes in this release.

Bug Fixes

UI Improvements

• Fixed relationship filterOptions not being applied within the list view
• Fixed timezone issues with date-only fields in Pacific timezones
• Fixed issues with prevent leave and autosave when the form is submitted but invalid
• Fixed database errors when running autosave operations
• Fixed selection status not updating after toggleAll in useSelection hook
• Fixed issues with unsaved changes allowing for scheduled publish missing changes
• Fixed JSON schema validation in the admin UI
• Fixed file size display for non-image uploads
• Fixed hide edit button on deleted relationship options
• Fixed hide array field "add" button if admin.readOnly: true is set
• Fixed browser back navigation issues after visiting list view
• Fixed minor issues with tabs and publish buttons in RTL mode

Database and Query Fixes

• Fixed MongoDB duplicative indexing of timestamps
• Fixed PostgreSQL countDistinct performance with table joins
• Fixed querying other collections via relationships inside blocks in PostgreSQL
• Fixed handling of document not found cases for update and delete operations in MongoDB
• Fixed populate being ignored for nested relationships

Rich Text Editor Fixes

• Fixed unindent button in toolbar never being active
• Fixed table element horizontal scrolling in HTML and JSX converters
• Improved Lexical version installation reliability

Other Fixes

• Fixed pre-flight OPTIONS request errors from the GraphQL endpoint
• Fixed versions not loading properly
• Fixed localized fields within block references not being handled properly
• Fixed upload and auth endpoints being mounted for all collections
• Fixed document header padding on tablet sized screens
• Fixed multi-tenant plugin default value for tenantsArrayTenantFieldName

New Features

Block References

You can now define blocks once in your Payload Config and reference them by slug wherever needed. This significantly reduces config size and improves performance by avoiding duplicate block definitions:

import { buildConfig } from 'payload'

const config = buildConfig({
  // Define blocks once
  blocks: [
    {
      slug: 'TextBlock',
      fields: [
        {
          name: 'text',
          type: 'text',
        },
      ],
    },
  ],
  collections: [
    {
      slug: 'collection1',
      fields: [
        {
          name: 'content',
          type: 'blocks',
          // Reference blocks by slug
          blockReferences: ['TextBlock'],
          blocks: [], // Required to be empty for compatibility
        },
      ],
    },
  ],
})

Route Transitions

The admin panel now shows a progress bar during page navigation, providing immediate visual feedback when loading new routes:

// Use Payload's Link component instead of Next.js Link
import { Link } from '@payloadcms/ui'

const MyComponent = () => {
  return (
    <Link href="/somewhere">
      Go Somewhere
    </Link>
  )
}

For programmatic navigation:

import { useTransition } from '@payloadcms/ui'
import { useRouter } from 'next/navigation'

const MyComponent = () => {
  const router = useRouter()
  const { startRouteTransition } = useRouteTransition()
 
  const redirectSomewhere = useCallback(() => {
    startRouteTransition(() => router.push('/somewhere'))
  }, [startRouteTransition, router])
  
  // ...
}

Join Fields Across Multiple Collections

Join fields can now query across multiple collections:

{
  slug: 'folders',
  fields: [
    {
      type: 'join',
      on: 'folder',
      collection: ['files', 'documents', 'folders'],
      name: 'children',
    },
    {
      type: 'relationship',
      relationTo: 'folders',
      name: 'folder',
    },
  ],
}

Confirmation Modal

A standardized confirmation modal component is now available:

'use client'
import { ConfirmationModal, useModal } from '@payloadcms/ui'
import React, { Fragment } from 'react'

const modalSlug = 'my-confirmation-modal'

export function MyComponent() {
  const { openModal } = useModal()

  return (
    <Fragment>
      <button
        onClick={() => {
          openModal(modalSlug)
        }}
        type="button"
      >
        Do something
      </button>
      <ConfirmationModal
        heading="Are you sure?"
        body="Confirm or cancel before proceeding."
        modalSlug={modalSlug}
        onConfirm={() => {
          // do something
        }}
      />
    </Fragment>
  )
}

Additional Features

• Added siblingFields argument to field hooks for easier access to related field data
• Added page query parameter for joins to support pagination
• Added support for interfaceName on radio and select fields to create reusable top-level types
• Added admin.components.listMenuItems option to inject custom components into list views
• Added hideFileInputOnCreate and hideRemoveFile options for upload collections
• Added Lithuanian language support

Security Updates

No significant security fixes were mentioned in this release.

Performance Improvements

Block References Performance

The new config.blocks property allows you to define blocks once and reference them by slug throughout your config. This significantly reduces the size of your Payload Config and improves performance in several ways:

1. Reduced Initial HTML Size: For a test case with 60 block fields each having 600 blocks, the initial HTML size was reduced from 195 kB to 73.6 kB.

2. Faster Type Generation: For the same test case, type generation time was reduced from 11 minutes to just 2 seconds, with the number of generated lines reduced from 461,209 to 35,810.

3. Optimized Permissions Calculation: Permissions for blocks are now calculated only once per block reference config, instead of once every time the blocks are referenced. This leads to significant performance improvements when navigating between pages in the admin UI.

Database Optimizations

• PostgreSQL Joins: Improved query performance when using table joins by optimizing the countDistinct operation. Instead of using SELECT (COUNT DISTINCT id) which is slow for large tables, the code now uses a more efficient window function approach.

• MongoDB Timestamps: Removed duplicative indexing of timestamp fields, which was causing warnings in mongoose 8.9.3+.

Other Performance Improvements

• Do not populate globals when calculating permissions, which speeds up permission calculations
• Ensure autosave doesn't run unnecessarily by only triggering when form data changes, not when form state changes
• Fixed database transaction errors caused by concurrent operations in autosave and document locking

Impact Summary

Payload CMS v3.24.0 delivers substantial performance improvements and quality-of-life enhancements that benefit both developers and content editors. The introduction of block references is a game-changer for projects with complex content structures, dramatically reducing config size and improving performance during type generation and permissions calculations.

For developers, this release brings better TypeScript support with improved component types, the ability to join across multiple collections, and new field hook capabilities. The addition of interfaceName for radio and select fields creates more reusable type definitions, while the standardized confirmation modal component reduces duplicative code.

Content editors will appreciate the smoother navigation experience with route transitions, better validation feedback, and improved UI for uploads. The fixes for timezone issues with date fields and autosave functionality enhance reliability, while the ability to see file sizes for all upload types improves the user experience.

Performance optimizations in database queries, especially for PostgreSQL users with complex joins, will result in faster page loads and better overall system responsiveness. The reduction in duplicative code through block references not only improves developer experience but also translates to faster admin panel performance.

Overall, this release represents a significant step forward in Payload's evolution, focusing on performance, developer experience, and UI refinements that make the CMS more efficient and enjoyable to use.

Full Release Notes