Payload CMS Release: 3.32.0

TL;DR

PayloadCMS 3.32.0: Orderable Collections, Performance Improvements, and Bug Fixes

This release introduces the highly requested orderable collections feature, allowing users to drag and drop rows to reorder them using fractional indexing for optimal performance. It also includes significant performance improvements for image handling, configurable job queue processing order, and fixes for several UI issues related to nested components and form state management.

Highlight of the Release

• New orderable collections feature with drag-and-drop functionality
• Performance improvements for image handling in document edit view
• Configurable job queue processing order (LIFO/FIFO)
• Fixed issues with nested custom components disappearing in forms
• Improved language switching with proper client config caching

Migration Guide

Orderable Collections

To use the new orderable collections feature, add the orderable: true property to your collection configuration:

import { CollectionConfig } from 'payload/types';

export const MyCollection: CollectionConfig = {
  slug: 'my-collection',
  orderable: true, // Enable drag-and-drop ordering
  fields: [
    // your fields here
  ],
};

Job Queue Processing Order

If you want to configure the job queue processing order, you can now do so in your jobs config:

export default buildConfig({
  // ...
  jobs: {
    processingOrder: 'fifo', // or 'lifo'
    // ...
  },
});

Or override it for specific queues:

await payload.jobs.run({
  queue: 'my-queue',
  processingOrder: 'lifo', // Override the default
  sequential: true, // For debugging
  // ...
});

Database Adapter Types

If you were importing types from database adapter subpaths like @payloadcms/db-mongodb/types, you can now import them directly from the main package:

// Before
import { MongoDBAdapter } from '@payloadcms/db-mongodb/types';

// After
import { MongoDBAdapter } from '@payloadcms/db-mongodb';

The /types subpath exports are still available for backward compatibility but will be removed in version 4.0.

Upgrade Recommendations

This release contains valuable features and important bug fixes without introducing breaking changes. We recommend all users upgrade to v3.32.0, especially if you:

• Need collection ordering functionality
• Experience issues with nested custom components in forms
• Use job queues with parallel tasks
• Want to benefit from the performance improvements for image handling

To upgrade:

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

If you're using PayloadCMS plugins or database adapters, make sure to update those as well:

npm install @payloadcms/db-mongodb@latest @payloadcms/richtext-lexical@latest
# Add any other plugins you use

After upgrading, test your application thoroughly, especially if you rely on nested custom components or job queues.

Bug Fixes

UI Fixes

• Fixed an issue where nested custom components (like Lexical rich text editor) would sometimes disappear when form state requests were invoked sequentially
• Fixed a problem where nested fields would disappear when manipulating rows in form state
• Query presets are now properly filtered to only show those related to the current collection
• Fixed client config caching to properly update when switching languages in the admin UI

Security and Data Integrity

• Improved protection against encoded and escaped open redirects in the getSafeRedirect utility
• Fixed support for parallel job queue tasks to prevent conflicts and ensure complete job logs
• Fixed an issue where fields in Lexical rich text drawers were incorrectly hidden due to improper permissions handling

Other Fixes

• Fixed TypeScript schema override to properly respect required: false settings
• Ensured client handlers for cloud storage plugins are added to import maps regardless of enabled state
• Improved Swedish translations for query presets

New Features

Orderable Collections

The most significant addition in this release is the new orderable boolean property for collections. When enabled, it allows users to drag and drop rows to reorder them in the admin UI. This highly requested feature uses fractional indexing to efficiently manage item order without requiring updates to all documents when reordering occurs.

Configurable Job Queue Processing Order

You can now configure whether job queues process tasks in FIFO (First In, First Out) or LIFO (Last In, First Out) order. This can be set globally in the jobs config or overridden on a per-queue basis using payload.jobs.run(). The release also adds a new sequential option for debugging purposes.

Version View Improvements

The default value for modifiedOnly in version views has been changed to true, making it easier to focus on fields that have actually changed between versions.

Database Adapter Enhancements

• Database adapters now return the database name to the unsanitized config, allowing plugins to access this information
• Types from database adapters are now exported directly from the main export, eliminating the need for separate /types imports

Security Updates

This release includes an important security fix for the Next.js integration. The getSafeRedirect utility has been improved to block encoded and escaped open redirects by:

• Normalizing and decoding redirect paths using decodeURIComponent
• Catching malformed encodings with a try/catch fallback
• Adding additional validation to block potential open redirect vectors

This enhancement helps prevent potential security vulnerabilities where maliciously crafted URLs could bypass redirect validation.

Performance Improvements

Optimized Image Handling

The document edit view now only downloads images (not other file types) and selects the most appropriate size to minimize unnecessary downloads. The system prioritizes the smallest available image within a target range (40px-180px) and falls back to the next best option when needed. This significantly reduces bandwidth usage - in one example, reducing transfer size from 4.5MB to just 15.9KB.

Async File System Operations

Synchronous file system operations like readFileSync have been replaced with their asynchronous counterparts (fs.promises.readFile) in contexts where async operations are already in use. This prevents blocking of the event loop, improving overall system performance and allowing more requests to run in parallel.

Query Building Optimization

The Drizzle database adapter now uses dynamic query building instead of query chaining, resulting in more type-safe, readable, and efficient code.

Impact Summary

PayloadCMS 3.32.0 delivers significant improvements across several areas of the platform. The headline feature is orderable collections, which enables drag-and-drop reordering of collection items using an efficient fractional indexing approach. This has been one of the most requested features and provides a much better user experience for content management.

Performance has been enhanced through optimized image handling in the admin UI and the use of asynchronous file system operations. The image optimization is particularly impactful, with examples showing a reduction in transfer size from 4.5MB to just 15.9KB in some cases.

Several critical bug fixes address issues with nested custom components disappearing in forms, which was particularly problematic for rich text editors embedded in arrays or blocks. The release also improves language switching by properly updating cached client configurations.

For developers, the new configurable job queue processing order provides more control over background tasks, and database adapter types are now more conveniently accessible directly from main exports. Security has been strengthened with better protection against open redirects in the Next.js integration.

Overall, this is a substantial quality-of-life update that improves both the developer and content editor experience without introducing breaking changes.

Full Release Notes