Payload CMS Release: 3.31.0

TL;DR

PayloadCMS v3.31.0: Query Presets and Performance Improvements

This release introduces Query Presets, allowing users to save and share collection filters, columns, and sort orders. It also includes significant performance improvements for the job queue system, security enhancements for redirects, and fixes for nested fields in various contexts. Armenian language support has been added, and several TypeScript packages now use strict mode.

Highlight of the Release

• New Query Presets feature allows saving and sharing filters, columns, and sort orders for collections
• Significant performance improvements in job queue operations with reduced database calls
• Enhanced security for login redirects with new safe redirect utility
• Added Armenian language translation
• Fixed issues with nested fields in various contexts including rich text and version views

Migration Guide

This release doesn't contain breaking changes, so upgrading from v3.30.0 should be straightforward.

Enabling Query Presets

To enable Query Presets for a collection:

{
  // Collection config
  slug: 'my-collection',
  // ...
  enableQueryPresets: true
}

For customizing Query Preset settings, use the root queryPresets property:

{
  // Payload config
  // ...
  queryPresets: {
    constraints: {
      read: [
        {
          label: 'Specific Roles',
          value: 'specificRoles',
          fields: [roles],
          access: ({ req: { user } }) => ({
            'access.update.roles': {
              in: [user?.roles],
            },
          }),
        },
      ],
    }
  }
}

Upgrade Recommendations

We recommend upgrading to v3.31.0 for all users, especially those who would benefit from:

• The new Query Presets feature for managing collection views
• Performance improvements in job queue operations
• Security enhancements for login redirects
• Armenian language support

This is a feature release with no breaking changes, making it a safe upgrade from v3.30.0. The performance improvements alone make this update worthwhile for applications with heavy database usage.

To upgrade:

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

Bug Fixes

• Auth Fields: Fixed an issue where auth fields were disrupting field paths within the field schema map, affecting version diff views
• JSON Fields: Added UUID fallback for non-secure contexts (HTTP) where crypto.randomUUID() is not available
• Next.js Integration:
  • Added safe redirect utility and applied it to login redirects for improved security
  • Fixed version view breaking for deeply nested tabs, rows, and collapsibles
• Rich Text Editor (Lexical):
  • Ensured proper initial state generation for nested Lexical fields, preventing multiple client-side fetches
• SEO Plugin: Corrected translation errors in the Spanish localization

New Features

Query Presets

The standout feature in this release is Query Presets, which allows users to save and share filters, columns, and sort orders for collections. This powerful feature enables:

• Saving complex filtering patterns and column configurations for reuse
• Sharing presets with team members for consistent data views
• Creating an unlimited number of preset configurations stored in the database
• Applying granular access control to determine who can read, update, and delete presets

To enable Query Presets for a collection, simply add enableQueryPresets: true to the collection's configuration. Once enabled, new controls appear in the list view of the admin panel for selecting and managing query presets.

Query Presets are stored in a dedicated payload-query-presets collection, making them fully CRUDable. Access control options include "only me", "everyone", and "specific users", with the ability to extend with custom rules like role-based access.

Armenian Language Support

This release adds Armenian language translation to PayloadCMS, expanding the platform's accessibility to Armenian-speaking users.

Security Updates

Security Improvements

This release introduces a new getSafeRedirect utility function to sanitize and validate redirect paths used in the login flow. This replaces the previous use of encodeURIComponent and inline string checks with a centralized, reusable, and more secure approach.

The utility function:

• Ensures redirect paths start with a single /
• Blocks protocol-relative URLs (e.g., //evil.com)
• Blocks JavaScript schemes (e.g., /javascript:alert(1))
• Blocks full URL redirects like /http: or /https:

This enhancement helps prevent potential redirect-based attacks in the authentication flow.

Performance Improvements

This release includes significant performance optimizations:

Job Queue Database Calls

Added an optional updateJobs database adapter method that dramatically reduces database calls for the job queue:

MongoDB Improvements:

• Before: Running 50 queued jobs required 51 database round trips (1 find + 50 updateOne operations)

• After: Only 2 database round trips (1 find + 1 updateMany)

• Before: Task completion required 2 database round trips (1 find + 1 updateOne)

• After: Only 1 database round trip (1 findOneAndUpdate)

Drizzle/Postgres Optimizations

Removed unnecessary db.select call in the updateOne operation when the document ID is already known, reducing sequential database operations.

Impact Summary

PayloadCMS v3.31.0 delivers significant value through its new Query Presets feature, which transforms how users interact with collection data by allowing them to save and share complex filtering patterns. This addresses a common pain point for teams working with large datasets and complex filtering needs.

The performance optimizations in this release are substantial, particularly for applications with heavy job queue usage. By reducing database round trips from 51 to just 2 when processing batches of jobs, systems will experience noticeably improved throughput and reduced database load.

Security enhancements for redirect handling strengthen the platform against potential redirect-based attacks, while the various bug fixes for nested fields improve reliability in complex form scenarios.

The addition of Armenian language support continues PayloadCMS's commitment to accessibility and internationalization.

For developers, the ability to render Lexical rich text fields outside of the EntityVisibilityProvider offers more flexibility in custom component development, and the TypeScript strict mode enablement in several packages improves type safety and developer experience.

Full Release Notes