Payload CMS Release: 3.30.0

TL;DR

Payload CMS v3.30.0 introduces important security updates, new features, and bug fixes. The release bumps the minimum required Next.js version to 15.2.3 to address a critical security vulnerability. Key features include MongoDB support for sorting by relationship fields, custom HTML element props in Next.js, and improved draft document handling. Bug fixes address permissions in bulk edit and draft document querying.

Highlight of the Release

• Security update: Minimum Next.js version bumped to 15.2.3
• MongoDB now supports sorting by fields in related collections
• Custom HTML element props support in Next.js integration
• Improved handling of draft documents in join fields
• Fixed permissions handling in bulk edit operations

Migration Guide

Upgrading Next.js

To comply with the new minimum version requirement, update your Next.js dependency to version 15.2.3 or higher:

npm install next@^15.2.3
# or
yarn add next@^15.2.3
# or
pnpm add next@^15.2.3

This is a mandatory update if you're using Next.js with Payload, as it addresses a critical security vulnerability.

No other migration steps are required for this release, as the other changes are additive or fix existing functionality without breaking changes to the API.

Upgrade Recommendations

This release is highly recommended for all users, especially those using Next.js integration, due to the security vulnerability addressed by bumping the minimum Next.js version.

The upgrade process should be straightforward:

1. Update your Payload dependency to v3.30.0
2. If using Next.js, ensure you update to at least version 15.2.3
3. Test your application thoroughly, especially if you use:
   • MongoDB with relationship field sorting
   • Custom HTML props in Next.js integration
   • Join fields with draft documents
   • Bulk edit functionality

No database migrations or configuration changes are required for this update.

Bug Fixes

Draft Document Handling in Join Fields

Fixed an issue where the draft: true flag was not being respected when querying documents for join fields. Previously, when querying a collection with a join field that had draft: true set, and the join field's collection also had versions.drafts: true, the database adapter would incorrectly query the original table/collection instead of the versions one.

Bulk Edit Field Permissions

Resolved a bug where top-level fields that lacked read or update permissions would still appear as options in the field selector within the bulk edit drawer. This ensures that users can only edit fields they have proper permissions for.

Conditional Logic Test Stability

Fixed flaky tests in conditional logic e2e tests. Since the introduction of loading states in nested fields (array and block rows), conditional logic tests would periodically fail because they wouldn't wait for loading states to resolve before continuing. This has been increasingly problematic since the introduction of form state queues.

New Features

MongoDB Relationship Field Sorting

MongoDB databases now support sorting by fields in other collections through relationship fields, bringing parity with Postgres and SQLite databases. This allows for more complex and flexible sorting operations when working with related data.

Example usage:

const result = await payload.find({
  collection: 'directors',
  depth: 0,
  sort: '-movies.name', // movies is a relationship field
})

Custom HTML Element Props in Next.js

Added support for passing additional props to the HTML element of Next.js RootLayout. This is particularly useful for integrating with UI libraries like Chakra UI that require custom font classes on the HTML element.

Example usage:

import { Rubik } from 'next/font/google'

const rubik = Rubik({
  subsets: ['latin'],
  variable: '--font-rubik',
})

const Layout = ({ children }: Args) => {
  return (
    <RootLayout htmlProps={{ className: rubik.variable }}>
      {children}
    </RootLayout>
  );
}

Security Updates

Next.js Security Vulnerability Mitigation

This release bumps the minimum required Next.js version from 15.0.0 to 15.2.3 to address a critical security vulnerability found in earlier Next.js versions. While this vulnerability does not directly affect Payload's core functionality, it could impact applications that have built additional functionality on top of Payload using Next.js middleware.

More details about the vulnerability can be found in the Next.js Blog post about CVE-2025-29927.

Performance Improvements

No specific performance improvements were highlighted in this release. The changes focus primarily on feature additions, security updates, and bug fixes.

Impact Summary

Payload CMS v3.30.0 delivers important security updates and feature enhancements that improve both developer experience and content management capabilities. The most significant change is the bump in minimum Next.js version to 15.2.3, addressing a critical security vulnerability. While this requires an update to your Next.js dependency, it's essential for maintaining security.

For MongoDB users, the addition of sorting by relationship fields brings parity with SQL databases, enabling more sophisticated data retrieval patterns. Next.js developers will appreciate the ability to add custom props to the HTML element, facilitating better integration with UI libraries like Chakra UI.

Content editors benefit from improved bulk edit functionality with proper permission handling, ensuring they only see fields they have access to modify. The fix for draft document handling in join fields ensures that content versioning works correctly across related collections.

Documentation improvements clarify proper usage of hooks and fix links to locked document documentation, while test stability improvements help ensure more reliable development workflows.

Overall, this release strengthens Payload's security posture while adding valuable features that enhance both development flexibility and content management capabilities.

Full Release Notes