Payload CMS is a modern, self-hosted headless content management system built with TypeScript, Node.js, and MongoDB. It's designed specifically for developers who want full control over their content management system while maintaining a powerful admin interface for content editors.
Payload CMS v3.39.0: Folders, Text Styling, and Performance Improvements
Payload CMS v3.39.0 introduces a major new feature: Folders, allowing you to organize documents across multiple collection types in a hierarchical structure. This release also brings text styling capabilities to the rich text editor, performance improvements for slow CPUs, and numerous bug fixes for database operations, UI components, and plugins. Group fields can now display their child fields as separate columns in list views, making data more scannable.
Highlight of the Release
New Folders feature for organizing documents across collections
TextStateFeature for applying custom styles to text in the rich text editor
Group fields can now display child fields as separate columns in list views
Performance improvements for useAsTitle fields on slower CPUs
Consistent database sorting even with non-unique fields
Migration Guide
Orderable Fields Change
If you're using the experimental orderable feature, note that orderable fields will no longer have required and unique constraints at the database schema level. This change was made to improve the development experience by automatically migrating collections that incorporate this property.
When a user adds the orderable property to a collection or join field, existing documents will have the order field set to undefined. The first time you try to reorder them, the documents will be automatically assigned an initial order, and you will be prompted to refresh the page.
Your database may prompt you to accept an automatic migration if you're using this feature. Since the orderable feature is still experimental, it may receive breaking changes without a major upgrade or contain bugs, so use it with caution.
Environment File Loading
The Payload CLI now correctly loads environment files based on the NODE_ENV setting. Previously, it would always load development-specific .env files even when NODE_ENV=production was explicitly set. If you were relying on this behavior, you may need to adjust your environment file setup.
Upgrade Recommendations
This release includes valuable new features like Folders and text styling, along with important performance improvements and bug fixes. It's recommended for all users to upgrade to v3.39.0, especially if you:
Need better document organization capabilities (Folders)
Want to apply custom text styling in the rich text editor
Have experienced performance issues with the useAsTitle field on slower machines
Use orderable fields with groups and tabs
Need more consistent database sorting behavior
The upgrade should be straightforward for most users, with the only potential migration being for those using the experimental orderable feature. As always, test the upgrade in a development environment before applying it to production.
Bug Fixes
Database Fixes
Fixed an issue where the same block slug in different places with different localized values would cause conflicts in Postgres
Ensured consistent sorting even when sorting on non-unique fields or when no sort parameters are provided
Removed limit from nested querying in MongoDB to fix pagination issues
UI Improvements
Fixed an issue where the request object wasn't being properly threaded through to views
Fixed rendering of missing group children fields for unnamed groups
Removed unnecessary spacing in sort column buttons
Fixed a bug where hidden: true wasn't respected for virtual fields that reference relationship fields
Plugin Fixes
Fixed the SEO plugin's image generation response parsing
Added translations for all UI elements and fields in the Import/Export plugin
Fixed multi-locale tenant select label and added missing translation for the Assigned Tenant field in the Multi-Tenant plugin
Other Fixes
Fixed an issue with environment file loading where files were always loaded as if in development mode
Fixed a bug where duplicate blocks weren't properly sanitized
Fixed a bug where orderable fields with groups and tabs required migration
Fixed an issue where images weren't visible in live preview when not running on port 3000
Fixed support for inline block types in strict mode for JSXConvertersFunction type in the Lexical rich text editor
Ensured the Create Payload App (CPA) always installs the latest version of templates
New Features
Folders
The most significant addition in v3.39.0 is the Folders feature. This allows you to organize your documents in a hierarchical structure, making content management more intuitive. You can enable folders on a per-collection basis and create folders from within the admin panel or via the API. Documents from multiple collection types can be stored within the same folder structure, and you can browse content either in the collection "By Folder" view or in the global "Browse by Folder" view.
Text Styling in Rich Text Editor
The new TextStateFeature for the Lexical rich text editor allows applying custom styles such as colors and background colors to text. This feature uses Lexical's State API to provide a more composable and maintainable approach to text styling than extending TextNode directly. The implementation includes a well-balanced default color palette that works well in both light and dark modes.
Group Fields as Separate Columns
Group fields can now display their child fields as separate columns in the list view. Previously, group fields were shown as a single column, but now each field within a group can be displayed individually, making data more scannable and accessible in collection list views.
Form Builder Date Field
The Form Builder plugin now includes a new date field type. This helps form serializers render the appropriate input for date values. The feature is disabled by default to avoid conflicts with existing projects but can be enabled with a simple configuration option.
Relationship Input Component
The relationship input component has been extracted for external use, making it easier to build custom UI components that leverage Payload's relationship field functionality.
Security Updates
No specific security fixes were mentioned in this release.
Performance Improvements
useAsTitle Field Performance
A significant performance improvement has been made to address lag when using the useAsTitle field on slower CPUs. Previously, entire React component trees would re-render on every keystroke of the useAsTitle field, causing significant performance issues that could make the admin panel nearly unusable on less powerful machines.
The fix isolates the document's title into its own context, ensuring that only components specifically subscribed to this context will re-render as the title changes. This dramatically reduces the rendering footprint and improves responsiveness, especially during rapid typing.
Linting Performance
The development experience has been improved with parallelized ESLint scripts that maintain readable logs through the use of --log-order=grouped. This makes the lint script significantly faster while still providing clear output.
Impact Summary
Payload CMS v3.39.0 delivers significant improvements to content organization and management with the introduction of Folders, allowing documents to be organized hierarchically across collections. Content editors will appreciate the improved UI performance, especially when working with useAsTitle fields on slower machines, and the ability to apply custom text styling in the rich text editor.
Developers gain access to extracted relationship components for custom UI development and benefit from more consistent database behavior. The changes to orderable fields eliminate the need for manual migrations, streamlining the development process.
The most impactful changes are:
Folders: A major new organizational feature that allows hierarchical document management across collections.
Text Styling: The new TextStateFeature enables rich styling options like colors and background colors in the Lexical editor.
Performance: Significant improvements to the useAsTitle field performance on slower CPUs by isolating the document title context.
Group Fields as Columns: Improved data visibility by displaying group field children as separate columns in list views.
Database Consistency: Better handling of sorting on non-unique fields and when no sort parameters are provided.
These improvements collectively enhance both the content management experience and the developer experience, making Payload more powerful and user-friendly.
Folders allow you to organize your documents in a more manageable way. Now you can enable folders on a per-collection basis and from there start adding folders from within the admin panel (or via the API). Once you have folders enabled you can then start organizing. You can create folders and store documents across multiple collection types and then view them either in the collection "By Folder" or in the global "Browse by Folder" view.
CleanShot.2025-05-21.at.21.49.16.mp4
show fields inside groups as separate columns in the list view (#7355) (2a41d3f)
plugin-form-builder: add new date field (#12416) (4dfb2d2)
richtext-lexical: add TextStateFeature (allows applying styles such as color and background color to text) (#9667) (fc83823)
ui: extracts relationship input for external use (#12339) (88769c8)
🐛 Bug Fixes
auto inject req.user into query preset constraints (#12461) (22b1858)
