Payload CMS Release: 3.0.0-beta.29

TL;DR

PayloadCMS 3.0.0-beta.29 introduces significant changes to component handling and type definitions. This release fixes issues with custom RSC components, separates label and description props, and improves label function handling. It also includes important bug fixes for the form-builder plugin and template installations. Several breaking changes affect how custom components are configured, particularly for descriptions and labels across globals, collections, and fields.

Highlight of the Release

• Fixed custom RSC component handling and separated label and description props
• Resolved label function handling issues
• Fixed form-builder plugin type exports and label value resolution
• Fixed template installation issues with yarn and Next.js versioning
• Removed several rich text types in favor of more streamlined alternatives

Migration Guide

for Breaking Changes

Component Structure Changes

1. Globals Config:

   • Move custom components from admin.description to admin.components.elements.Description

2. Collections Config:

   • Move custom components from admin.description to admin.components.edit.Description

3. All Fields:

   • Move custom components from field.admin.description to field.admin.components.Description

4. Collapsible Field:

   • Move custom components from field.label to field.admin.components.RowLabel

5. Array Field:

   • Note that field.admin.components.RowLabel no longer accepts strings or records

Field Components Changes

If you're using exported field components in your app:

• The labelProps property has been stripped down
• It no longer contains the label and required props
• These properties can now only be configured at the top-level

Rich Text Type Changes

• Replace LexicalBlock with Block
• Replace RichTextFieldRequiredEditor with RichTextField
• Replace FieldWithRichTextRequiredEditor with Field

Upgrade Recommendations

This beta release contains several breaking changes that affect component handling and type definitions. We recommend:

1. For Production Applications:

   • Wait for the stable 3.0.0 release unless you specifically need these fixes
   • Test thoroughly in a development environment before upgrading

2. For Development/Testing Environments:

   • Upgrade to this beta to test your application against the latest changes
   • Pay special attention to custom components and rich text implementations
   • Follow the migration guide to update component paths and type usage

3. For New Projects:

   • Use this beta version as it contains important fixes for template installations
   • Be aware that further breaking changes may occur before the stable release

When upgrading, make sure to update your package.json to specify "payload": "^3.0.0-beta.29" and run npm install or yarn install to update your dependencies.

Bug Fixes

Form Builder Plugin Fixes

• Resolved issue with labelValue resolution from LabelFunction in the form-builder plugin
• Fixed type export issues in the form-builder plugin

Template Installation Fixes

• Fixed broken yarn installation process for new template installs
• Pinned Next.js version in blank-3.0 template to prevent installation failures
• Improved stability of template initialization process

New Features

Component Handling Improvements

• Fixed non-functional custom React Server Component (RSC) handling
• Separated label and description props for better component organization
• Fixed non-functional label function handling
• Improved component structure for better maintainability and clarity

Rich Text Type Refinements

• Streamlined rich text type system by removing redundant types
• Simplified developer experience by consolidating similar types

Security Updates

No security fixes were mentioned in this release.

Performance Improvements

No specific performance improvements were mentioned in this release.

Impact Summary

PayloadCMS 3.0.0-beta.29 brings significant improvements to component handling and fixes several critical bugs, but introduces breaking changes that require code updates. The release enhances the stability of custom React Server Components, improves the form-builder plugin, and fixes template installation issues. Developers will need to update their code to accommodate the new component structure, particularly for custom descriptions and labels. The removal of several rich text types in favor of more streamlined alternatives also requires code changes. While these changes improve the overall architecture and maintainability of PayloadCMS, they do require careful migration planning. The fixes to template installations ensure a smoother onboarding experience for new users, making this an important release despite its beta status.

Full Release Notes