Payload CMS Release: 3.0.0-beta.24

TL;DR

Payload CMS 3.0.0-beta.24 introduces breaking changes to plugin exports, requiring all plugins to use consistent named exports. The Lexical rich text editor received significant API updates for custom features. New features include custom login redirects in Next.js and improvements to the rich text editor. Bug fixes address issues with GraphQL locale handling, form state management, and dependency issues.

Highlight of the Release

• Breaking change: All plugins now use consistent named exports with standardized naming pattern
• Breaking change: Lexical rich text editor API updates for custom features
• New feature: Support for custom login redirects in Next.js applications
• Bug fix: Improved GraphQL locale handling through relationships
• Bug fix: Form save button now only enabled after modifications
• Bug fix: Password confirmation field now properly persists in form state

Migration Guide

Plugin Import Updates

All plugins now use consistent named exports. Update your imports as follows:

// Before
import { cloudStorage } from '@payloadcms/plugin-cloud-storage'
// Now
import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'

// Before
import { payloadCloud } from '@payloadcms/plugin-cloud'
// Now
import { payloadCloudPlugin } from '@payloadcms/plugin-cloud'

// Before
import formBuilder from '@payloadcms/plugin-form-builder'
// Now
import { formBuilderPlugin } from '@payloadcms/plugin-form-builder'

// Before
import { nestedDocs } from '@payloadcms/plugin-nested-docs'
// Now
import { nestedDocsPlugin } from '@payloadcms/plugin-nested-docs'

// Before
import { redirects } from '@payloadcms/plugin-redirects'
// Now
import { redirectsPlugin } from '@payloadcms/plugin-redirects'

// Before
import search from '@payloadcms/plugin-search'
// Now
import { searchPlugin } from '@payloadcms/plugin-search'

// Before
import { sentry } from '@payloadcms/plugin-sentry'
// Now
import { sentryPlugin } from '@payloadcms/plugin-sentry'

// Before
import { seo } from '@payloadcms/plugin-seo'
// Now
import { seoPlugin } from '@payloadcms/plugin-seo'

Lexical Rich Text Editor API Changes

If you have custom Lexical features, you'll need to update them:

1. Rename floatingSelectToolbar to toolbarInline
2. Change slashMenu.dynamicOptions and slashMenu.options to slashMenu.groups and slashMenu.dynamicGroups
3. Rename toolbarFixed.sections to toolbarFixed.groups
4. Update slash menu group options and toolbar group entries to items
5. Change toolbar group item onClick to onSelect
6. Wrap editor.update manually in slashMenu item onSelect handlers
7. Convert slash menu items from classes to object types with key as a property
8. Update CSS classnames for slash menu and toolbars
9. Rename CheckListFeature to ChecklistFeature

For detailed migration examples, refer to the PR diff: https://github.com/payloadcms/payload/pull/6191/files

Upgrade Recommendations

For Developers Using Plugins

This is a breaking change release that requires updates to plugin imports and potentially custom Lexical rich text features. We recommend:

1. Update all plugin imports to use the new naming convention
2. If you have custom Lexical rich text features, update them according to the migration guide
3. Test your application thoroughly after these changes

For Plugin Developers

You must update your plugin exports to use the new naming convention to maintain compatibility with Payload 3.0.0-beta.24 and above.

Since this is still a beta release, these changes are expected as the API stabilizes toward the final 3.0.0 release.

Bug Fixes

GraphQL Locale Handling

Fixed an issue where GraphQL locale settings weren't properly cascading through relationships, ensuring consistent localization throughout related content.

Form State Management

• Fixed an issue where the save button was enabled even when no form modifications were made
• Ensured that the confirm password field remains properly in the form state
• Moved ts-essentials from dev dependencies to production dependencies to resolve runtime issues

New Features

Custom Login Redirects in Next.js

Added support for custom login redirects in Next.js applications through the initPage function, giving developers more control over authentication flows.

Lexical Rich Text Editor Improvements

Finalized the ClientFeature interface for the Lexical rich text editor, providing a more consistent and robust API for custom feature development.

Security Updates

No security fixes were mentioned in this release.

Performance Improvements

No specific performance improvements were highlighted in this release.

Impact Summary

This release introduces significant breaking changes to plugin imports and the Lexical rich text editor API, requiring code updates for anyone using plugins or custom Lexical features. The standardization of plugin exports improves consistency across the ecosystem but necessitates updates to import statements in existing code.

The Lexical rich text editor API changes are more extensive, affecting property names, event handlers, and component structure for custom features. While these changes improve the API's consistency and robustness, they require careful migration for custom implementations.

On the positive side, the release adds useful features like custom login redirects for Next.js applications and fixes several bugs related to form state management and GraphQL locale handling. These improvements enhance the developer and content editor experience without requiring significant adaptation.

Overall, this beta release continues to refine the API toward the final 3.0.0 release, with breaking changes that are expected during the beta phase but deliver a more consistent and robust foundation.

Full Release Notes

// before
import { cloudStorage } from '@payloadcms/plugin-cloud-storage'
// current
import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage'

// before
import { payloadCloud } from '@payloadcms/plugin-cloud'
// current
import { payloadCloudPlugin } from '@payloadcms/plugin-cloud'

// before
import formBuilder from '@payloadcms/plugin-form-builder'
// current
import { formBuilderPlugin } from '@payloadcms/plugin-form-builder'

// before
import { nestedDocs } from '@payloadcms/plugin-nested-docs'
// current
import { nestedDocsPlugin } from '@payloadcms/plugin-nested-docs'

// before
import { redirects } from '@payloadcms/plugin-redirects'
// current
import { redirectsPlugin } from '@payloadcms/plugin-redirects'

// before
import search from '@payloadcms/plugin-search'
// current
import { searchPlugin } from '@payloadcms/plugin-search'

// before
import { sentry } from '@payloadcms/plugin-sentry'
// current
import { sentryPlugin } from '@payloadcms/plugin-sentry'

// before
import { seo } from '@payloadcms/plugin-seo'
// current
import { seoPlugin } from '@payloadcms/plugin-seo'