Payload CMS Release: 3.17.0

TL;DR

Payload CMS v3.17.0 brings significant improvements to the rich text editor with Lexical 0.21.0 upgrade, adds ability to delete scheduled publish events, improves admin UI components, and fixes numerous bugs across the platform. Key highlights include better table handling in the rich text editor, localized placeholders, and improved error handling. Note: Users should upgrade to v3.17.1 due to potential richtext-lexical dependency issues in this version.

Highlight of the Release

• Lexical rich text editor upgraded from 0.20.0 to 0.21.0 with improved table handling
• New ability to delete scheduled publish events after they've been created
• Added support for localized placeholders in the rich text editor
• New paragraph button added below the rich text editor for easier content creation
• Option to disable cache tags for admin thumbnails when using third-party CDNs

Migration Guide

Upgrading from v3.16.0 to v3.17.0

1. Important Note: It's recommended to upgrade directly to v3.17.1 instead of v3.17.0, as v3.17.0 may encounter richtext-lexical dependency checker errors during development.

2. Lexical Upgrade (0.20.0 to 0.21.0):

   • If you're using the rich text editor, ensure you're importing Lexical packages through Payload's re-exports:

   // Correct way
   import { $createParagraphNode } from '@payloadcms/richtext-lexical/lexical';
   
   // Incorrect way - may break
   import { $createParagraphNode } from 'lexical';
   

3. Custom Rich Text Formats:

   • If you were relying on the highlight format in Lexical, it's now properly supported without alteration to the core constants.

4. Next.js Integration:

   • If you're using Next.js with the basePath option, the REST API now properly respects this configuration.

5. Custom Label Components:

   • If you have custom label components in table columns, they now receive proper field props and server props. You may need to update your components to handle these additional props.

No database migrations are required for this update.

Upgrade Recommendations

Priority: Medium

It's recommended to upgrade to v3.17.1 (not v3.17.0) as soon as convenient, especially if you:

1. Use the rich text editor with tables or need the improved placeholder localization
2. Need to manage scheduled publish events
3. Use Next.js with the basePath option
4. Have experienced any of the specific bugs fixed in this release

The upgrade process is straightforward with no breaking changes, but as always, test thoroughly in a development environment before deploying to production.

For projects using third-party CDNs that don't support additional search parameters, the new cacheTags option for admin thumbnails will be particularly valuable.

Bug Fixes

Rich Text Editor Fixes

• Fixed issue where lexical editor behind a drawer was incorrectly registered as parent editor of lexical editor within drawer
• Fixed incorrect padding for editor placeholder on small viewports
• Fixed error when deleting links in the editor
• Fixed overlap between insert paragraph button and floating link toolbar
• Combined and fixed two different implementations of normalizeMarkdown with proper code block regex
• Removed alteration of lexical text format constant to enable highlight format

UI and Rendering Fixes

• Fixed hydration issues with date fields in list view
• Fixed issue with updatedAt timestamps not updating in the UI when drafts are updated
• Fixed table custom label components missing client field props
• Fixed scheduled publish not showing related events in PostgreSQL
• Fixed pagination reset when typing in WhereBuilder select menu
• Ensured server props are passed to custom label components within table columns

Framework Integration Fixes

• Fixed REST API compatibility with Next.js basePath option
• Ensured req.locale is populated before running access control in Next.js
• Fixed localized tabs with empty data and array fields inside leading to crash in afterChange
• Fixed Estonian translations type to properly use DefaultTranslationsObject

Other Fixes

• Improved error logging during onInit and website template seed
• Fixed e2e test suite retries
• Fixed issue with shadcn utilities alias across website template
• Improved response header handling to respect immutability
• Added better error messaging when no argument is passed to Payload CLI

New Features

Rich Text Editor Improvements

• Lexical Upgrade: Updated from 0.20.0 to 0.21.0, fixing table selection and scrollable table bugs
• New Paragraph Button: Added a convenient button below the editor to easily add new paragraphs
• Custom Block Icons: Block and inline block icons in the slash menu/toolbars can now be customized using the imageURL property
• Localized Placeholders: Added support for localizing editor placeholders according to language preferences

Admin UI Enhancements

• Scheduled Publish Management: Users can now delete scheduled publish events after they've been created
• Cache Tag Control: Added ability to disable cache tags for admin thumbnails via the cacheTags boolean option (default: true), helpful when using third-party CDNs that don't allow additional search parameters

Developer Experience

• Consolidated Update Operations: Logic between update and updateByID operations has been consolidated, making future enhancements and fixes easier to implement across both operations

Security Updates

This release doesn't include any specific security fixes or improvements.

Performance Improvements

This release doesn't include specific performance-focused improvements, but several changes may indirectly improve performance:

1. The consolidation of logic between update and updateByID operations creates a more efficient codebase that's easier to maintain and optimize.

2. The fix for hydration issues with date fields in list view improves client-side rendering performance by adding a "Loading..." fallback while the dateFNS Locale is loaded, preventing hydration mismatches.

3. The improved error logging during onInit and website template seed helps identify performance bottlenecks earlier in the development process.

4. The ability to disable cache tags for admin thumbnails can improve loading performance when working with third-party CDNs that don't support additional search parameters.

Impact Summary

Payload CMS v3.17.0 delivers significant improvements to the rich text editing experience through the Lexical 0.21.0 upgrade, addressing several table-related bugs and adding useful features like a new paragraph button and localized placeholders. Content editors will appreciate the ability to delete scheduled publish events, providing more control over content publishing workflows.

Developers benefit from consolidated update operations, improved error handling, and better Next.js integration. The option to disable cache tags for admin thumbnails solves compatibility issues with certain third-party CDNs.

UI improvements include fixed timestamps for draft updates, better custom label component support, and resolved hydration issues with date fields. The release also includes documentation updates and template fixes.

While not introducing any breaking changes, users should upgrade directly to v3.17.1 instead of v3.17.0 to avoid potential richtext-lexical dependency issues during development.

Full Release Notes