Payload CMS Release: 3.21.0

TL;DR

Payload CMS v3.21.0 introduces auto-resizing textareas, improved TypeScript schema generation, and enhanced multi-tenant plugin capabilities. This release includes significant fixes for PostgreSQL database operations, search plugin functionality, and UI components. Documentation has been expanded for admin preview features, and numerous template improvements enhance developer experience across various environments.

Highlight of the Release

• Auto-resizing textarea fields that dynamically adjust height based on content
• Improved TypeScript schema generation with exposed helpful arguments
• Option to opt out of tenant access control merge in the multi-tenant plugin
• Fixed PostgreSQL database issues with polymorphic joined collections
• Enhanced search plugin functionality with proper document URL generation

Migration Guide

Deprecated Features

1. Search Plugin apiBasePath Config Property The apiBasePath property in the Search Plugin config has been deprecated as it was unnecessarily exposed. The plugin now reads this property directly from the Payload config. If you're currently using this property, you can safely remove it from your search plugin configuration.

2. body-scroll-lock Package The body-scroll-lock package has been deprecated in preparation for future updates. While no immediate action is required, consider planning for alternative solutions in future releases.

Form Field Properties

If your code relies on the explicit presence of valid and passesCondition properties in form state, be aware that these properties are now being added back to maintain backward compatibility. In the next major release, this behavior may change, so consider updating your logic to handle cases where these properties might not be explicitly set.

Upgrade Recommendations

This release contains numerous bug fixes and improvements with no breaking changes, making it a recommended upgrade for all Payload CMS users.

Priority: Medium

Steps to upgrade:

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

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

2. If you're using the multi-tenant plugin and want to opt out of tenant access control merge, you can now do so by setting useTenantsCollectionAccess: false in your plugin configuration.

3. If you're using the search plugin, be aware that the apiBasePath property is now deprecated. The plugin will automatically use the correct path from your Payload configuration.

4. If you're using templates or examples, note that pnpm has been set to version 9 due to compatibility issues with pnpm v10 and the sharp package.

No database migrations or special handling is required for this update.

Bug Fixes

PostgreSQL Database Fixes

• Fixed write operations on polymorphic joined collections that were previously throwing errors
• Resolved issues with select hasMany fields inside arrays and blocks when versions are enabled
• Fixed incorrect tenant selection with PostgreSQL that caused NaN errors in list views

UI Improvements

• Fixed the create-first-user flow crashing when users collection has join fields
• Resolved errors in version view when documents contain localized arrays or blocks
• Fixed form field properties for valid and passesCondition values in client-side form state

Search Plugin Fixes

• Fixed search plugin generating incorrect document URLs when using custom base paths
• Resolved issue where search documents were being deleted even when published versions existed
• Fixed API route resolution by using the useConfig hook instead of resolving during initialization

Rich Text Editor Fixes

• Fixed link drawer not displaying fields when parent document's create access control is set to false
• Removed CSS dependency from JSX converter to improve versatility across different runtimes

Multi-tenant Plugin Fixes

• Fixed hardcoded user tenants field that caused issues when using custom slugs and field names
• Resolved tenant selector resetting to the first option when loading a document

New Features

Auto-resizing Textarea Fields

Textarea fields now automatically adjust their height based on content, providing a more intuitive editing experience. This eliminates the need for manual resizing and improves the overall user experience when working with longer text content.

Enhanced TypeScript Schema Generation

The TypeScript schema generation system now exposes helpful arguments to the config.typescript.schema functions, making it easier to reuse utility functions like fieldsToJSONSchema in plugins and custom code.

Multi-tenant Plugin Improvements

The multi-tenant plugin now allows opting out of tenant access control merge with the new useTenantsCollectionAccess configuration option. Setting this to false enables users to write their own access control functions without the plugin merging in its own constraints for the tenant collection.

Security Updates

No significant security fixes were included in this release.

Performance Improvements

Form State Optimization

Small performance optimization in form state handling by keeping the old object reference of fields if they did not change when server form state comes back.

Package Dependencies Update

Updated various build dependencies including Babel, esbuild, SWC, and React compiler packages to their latest versions, which should result in more efficient builds and potentially better runtime performance.

Faceless UI Package Updates

Updated @faceless-ui/window-info to v3.0.1 and @faceless-ui/scroll-info to v2.0.0, which include React 19 stable in their peer dependencies and various performance improvements.

Impact Summary

Payload CMS v3.21.0 delivers significant improvements across multiple areas, with a focus on enhancing developer experience and fixing critical issues. The introduction of auto-resizing textareas improves content editing workflows, while the expanded TypeScript schema generation capabilities provide developers with more flexibility when extending Payload's type system.

PostgreSQL users will benefit from several important fixes addressing polymorphic joined collections and select hasMany fields inside arrays and blocks with versions. The multi-tenant plugin receives notable enhancements with the ability to opt out of tenant access control merge and fixes for tenant selection issues.

The search plugin has been significantly improved with better document URL generation, proper handling of published versions, and fixed API route resolution. Documentation has been expanded for admin preview and draft preview features, providing clearer guidance on these powerful capabilities.

This release represents a solid iteration that addresses user feedback and pain points while introducing useful new features that enhance the overall Payload CMS experience.

Full Release Notes