Payload CMS Release: 3.37.0

TL;DR

Payload CMS v3.37.0 brings significant UI enhancements, including configurable placeholders for select and relationship fields, improved filtering for array fields, and new ways to interact with related documents. The release also fixes critical bugs in GraphQL, block fields, and cloud storage plugins, while adding useful login helper utilities for plugin developers.

Highlight of the Release

• Enhanced UI for relationship fields with configurable placeholders and ability to open related documents in new tabs
• Added filtering capabilities for array fields in list views
• Fixed critical issues with block fields and form state management
• Exported login helper utilities for plugin developers
• Improved database migration processes and cloud storage plugin functionality

Migration Guide

No breaking changes were introduced in this release, so no migration is required when upgrading from v3.36.1 to v3.37.0.

If you're using any of the following features, you may want to take advantage of the new capabilities:

1. Select and Relationship Fields: You can now customize placeholders using the admin.placeholder property:

   {
     name: 'category',
     type: 'select',
     options: [...],
     admin: {
       placeholder: 'Choose a category'
       // or for translations
       placeholder: i18n.__('category.placeholder')
     }
   }
   

2. Live Preview: You can now pass a custom request handler to the subscribe function:

   subscribe({
     depth: 2,
     collectionPopulationRequestHandler: async (url) => {
       const response = await fetch(url, {
         headers: {
           Authorization: `JWT ${token}`
         }
       })
       return await response.json()
     }
   })
   

3. Login Helper Utilities: If you're building plugins that interact with authentication, you can now import these utilities:

   import { 
     isUserLocked, 
     checkLoginPermissions, 
     jwtSign, 
     getFieldsToSign,
     incrementLoginAttempts,
     resetLoginAttempts,
     UnverifiedEmail
   } from 'payload'
   

Upgrade Recommendations

This release is recommended for all Payload CMS users as it includes important bug fixes and useful new features without introducing breaking changes.

Priority: Medium

Who should upgrade immediately:

• Users experiencing issues with block fields in forms
• Users working with cloud storage plugins and versioned media
• Developers building plugins that need access to login helper utilities
• Anyone using relationship fields who would benefit from improved navigation options

Upgrade Steps:

1. Update your Payload CMS dependency to v3.37.0:

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

2. If you're using TypeScript, rebuild your types:

   payload generate:types
   

3. Restart your development server to apply the changes

No additional configuration changes are required for this update.

Bug Fixes

UI and Form Handling

• Fixed issue where blockType was ignored when merging server form state, preventing proper block field rendering
• Fixed version list status for unpublished documents that incorrectly showed as "Currently published version"
• Fixed search functionality for nested fields in WhereBuilder field selection
• Fixed RelationshipFilter to update when only filterOptions are changed

GraphQL

• Fixed nextPage and prevPage fields being non-nullable in GraphQL schema even though they can be null in certain cases
• Fixed population of joins that target relationship fields with relationTo as an array

Database and Migration

• Fixed migration batch not incrementing past 1 when running payload migrate
• Fixed PostgreSQL transaction timeout during v2-v3 migration by starting transaction after Drizzle prompts

Plugins

• Fixed missing 'prefix' issue in cloud storage plugin when working with versioned media
• Fixed tenant selector to respect order when 'orderable' is enabled for tenant collection
• Fixed create-payload-app overwriting existing environment variables in .env files

Rich Text

• Added missing line-breaks to plaintext conversion for headings, lists, list items, tables, table rows, and table cells

New Features

UI Enhancements

• Configurable Placeholders: Select and relationship fields now support custom placeholder text through the admin.placeholder property
• Related Document Navigation: Added ability to open related documents in a new tab directly from relationship fields
• Document Links in Drawers: Added option to open the current document in a new tab when opened in a drawer
• Array Field Filtering: Array fields can now be filtered in list views like other field types

Developer Tools

• Login Helper Utilities: Exported additional login helper utilities for plugin developers:
  • isUserLocked - Check if a user is locked due to too many invalid attempts
  • checkLoginPermissions - Verify user lock status and email verification
  • jwtSign - Payload's internal JWT signing approach
  • getFieldsToSign - Reduce document fields for JWT creation
  • incrementLoginAttempts / resetLoginAttempts - Handle login attempt tracking
  • UnverifiedEmail - Error for unverified email login attempts

Live Preview Improvements

• Custom Request Handlers: Added ability to pass a custom collectionPopulationRequestHandler function to subscribe, enabling custom headers for authentication

Security Updates

No specific security fixes were mentioned in this release. The exported login helper utilities may help developers implement more secure authentication flows in their plugins, but there were no explicit security vulnerabilities addressed in this release.

Performance Improvements

This release doesn't include specific performance improvements as the primary focus was on feature enhancements and bug fixes. However, several of the bug fixes may indirectly improve performance in specific scenarios:

1. The fix for relationship filters updating when only filterOptions change will reduce unnecessary re-renders
2. The fix for block type handling in form state merging will prevent errors that could cause performance degradation
3. The database migration batch incrementing fix will improve the reliability of migration processes

Impact Summary

Payload CMS v3.37.0 delivers a substantial quality-of-life update focused on improving the user experience for both content editors and developers.

For content editors, the release brings significant UI enhancements that streamline workflows when working with related content. The ability to open related documents in new tabs and access document links from drawers makes navigation more intuitive. Improved filtering for array fields and more accurate version status labels enhance content management capabilities.

For developers, the release provides greater customization options with configurable placeholders for select and relationship fields, and exports useful login helper utilities for plugin development. Critical bug fixes for block fields, GraphQL pagination, and cloud storage plugins improve reliability and prevent potential data corruption issues.

System administrators will benefit from more robust database migration processes and fixes to environment variable handling in create-payload-app.

Overall, this release represents a solid improvement to Payload's usability and reliability without introducing breaking changes, making it a recommended upgrade for all users.

Full Release Notes