TL;DR

Payload CMS v1.4.0 introduces significant improvements to the rich text editor, document drawers, and relationship fields. This release includes a breaking change to API Key authentication headers, now using collection slugs instead of labels. It also adds Czech language support, fixes numerous bugs related to drafts, autosave, and file uploads, and upgrades GraphQL to version 16. The update enhances the user experience with better document permissions visibility and improved rich text editing capabilities, particularly for nested lists.

Highlight of the Release

• Breaking change to API Key authentication header format
• Upgraded to GraphQL 16
• Added Czech language translation
• Enhanced rich text editor with improved nested list support
• New drawer UI for uploads and rich text relationships
• Fixed issues with draft versions querying
• Added document permissions visibility to account view
• Improved relationship field search with special character support

Migration Guide

API Key Authentication Header Format Change

The format for API Key authentication headers has changed from using collection labels to using collection slugs:

Previous format:

${collection.labels.singular} API-Key ${apiKey}

New format:

${collection.slug} API-Key ${apiKey}

Migration Steps:

1. Identify all places in your code where you're using API Key authentication headers
2. Update the header format to use collection slugs instead of labels
3. Test your API requests to ensure they're working with the new header format

GraphQL 16 Upgrade

This release upgrades GraphQL from version 15 to 16. While this should be mostly transparent to users, if you're using custom GraphQL code or plugins, you may need to review the GraphQL 16 release notes for any breaking changes that might affect your implementation.

Upgrade Recommendations

This release contains a breaking change to the API Key authentication header format, so careful testing is recommended before upgrading in production environments.

Priority: Medium-High

• For development environments: Upgrade at your earliest convenience to benefit from the new features and bug fixes.
• For production environments: Plan for the upgrade and test thoroughly, especially if you're using API Key authentication in your application.

Upgrade Steps:

1. Update your Payload CMS dependency to version 1.4.0:

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

2. Update any code using API Key authentication headers to use collection slugs instead of labels.

3. If you're using custom GraphQL implementations, review for compatibility with GraphQL 16.

4. Test your application thoroughly, especially features related to:

   • API Key authentication
   • Rich text editing
   • File uploads
   • Document relationships
   • Draft versions and autosave functionality

Bug Fixes

Document and Field Management Fixes

• Draft Versions: Fixed issue #1611 where users were unable to query draft versions with draft=true
• Globals and Autosave: Resolved issue #1698 with globals and autosave not working properly
• Autosave Conflict: Fixed issue #1748 where autosave would conflict when a document is published during the autosave process
• Rich Text in Arrays: Fixed issue #1747 where rich text in arrays was improperly updating initialValue when moving rows
• Row Field Labels: Removed unnecessary labels from row field type (issue #1752)

File Upload Fixes

• SVG Image Dimensions: Now properly saving image dimensions to SVG uploads (issue #1738)
• File Reselection: Fixed issues with missing files after reselection in upload component
• Cleared File Reselection: Now allows cleared files to be reselected

UI and Interaction Fixes

• Sort Clearing: Safely clears sort to prevent issues (issue #1736)
• Relationship Labels: Updated relationship label on drawer save and prevented stepnav updates
• Document Drawer Refresh: Now refreshes document drawer on save
• Duplicating Documents: Removed update and created at fields when duplicating documents
• Radio Validation: Simplified radio validation for better reliability
• Translated Tab Classnames: Fixed issues with translated tab classnames

New Features

Rich Text and Document Drawer Enhancements

• New Drawer UI Integration: Added drawer UI for rich text elements including uploads, links, and relationships
• New useListDrawer Hook: Created a complementary hook to the existing useDocumentDrawer
• Enhanced Rich Text Toolbar: Improved positioning when inside a drawer
• Document Permissions in Account View: Users can now see their document permissions in the account view

Language and API Improvements

• Czech Language Support: Added complete Czech translation
• GraphQL 16 Upgrade: Updated GraphQL to version 16, providing access to new features and improvements
• Improved Relationship Field Search: Now properly handles special characters in search queries

Rich Text Editor Improvements

• Better Nested List Support: Fixed issues with rich text nested list structure
• List Indentation: Added support for left indentation of lists
• Relationship and Upload Elements: Now can reside within lists

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Query Performance

• Now uses MongoDB aggregate query if draft=true is specified, improving performance when querying draft versions
• Optimized relationship field search to better handle special characters without performance degradation

UI Performance

• Improved rich text toolbar positioning calculations for better performance inside drawers
• Enhanced document drawer refresh mechanism to be more efficient
• Optimized autosave process to avoid unnecessary operations when a document is published

Impact Summary

Payload CMS v1.4.0 delivers significant improvements to the editing experience while introducing one important breaking change to API Key authentication.

The most notable impact is on developers who use API Key authentication, as they'll need to update their code to use collection slugs instead of labels in authentication headers. This change makes the authentication system more consistent but requires immediate attention during upgrade.

Content editors will benefit substantially from this release with numerous improvements to the rich text editor, including better nested list support, enhanced relationship field search, and a new drawer UI for managing uploads and relationships within rich text. The fixes to autosave, draft versions, and file uploads also address several pain points in the content editing workflow.

Administrators gain improved visibility with document permissions now visible in the account view, making it easier to manage user access.

The GraphQL 16 upgrade provides a foundation for future improvements and access to newer GraphQL features, though most users won't notice immediate differences unless they're using custom GraphQL implementations.

Overall, this release balances new features with important bug fixes, making it a worthwhile upgrade despite the breaking change to API Key authentication.

Full Release Notes