Payload CMS Release: 3.0.0-beta.15

TL;DR

PayloadCMS v3.0.0-beta.15 introduces significant changes to the richtext-lexical editor with improved population behavior and field hooks. This release includes breaking changes to request handling in custom handlers and richtext data structure. Key improvements include fixes for user creation, PostgreSQL UUID handling, and enhanced richtext features. Developers should carefully review the migration guide before upgrading.

Highlight of the Release

• Breaking changes to request handling in custom handlers with new utilities
• Reworked richtext-lexical population behavior with improved node typing
• Fixed critical issues with first user creation
• Added loading indicators for block nodes in richtext editor
• Fixed PostgreSQL UUID handling
• Improved richtext field validation and hooks

Migration Guide

Breaking Changes Migration Guide

Custom Request Handlers

Custom handlers will no longer automatically resolve data, locale, and fallbackLocale. You must now use the provided utilities:

// Before
{
  path: '/whoami/:parameter',
  method: 'post',
  handler: async (req) => {
    return Response.json({
      name: req.data.name, // data will be undefined
      // locales will be undefined
      fallbackLocale: req.fallbackLocale,
      locale: req.locale,
    })
  }
} 

// After
import { addDataAndFileToRequest } from '@payloadcms/next/utilities'
import { addLocalesToRequest } from '@payloadcms/next/utilities'

{
  path: '/whoami/:parameter',
  method: 'post',
  handler: async (req) => {
    // mutates req, must be awaited
    await addDataAndFileToRequest(req)
    
    // mutates req
    addLocalesToRequest(req)
    
    return Response.json({
      name: req.data.name, // data is now available
      fallbackLocale: req.fallbackLocale, // locales available
      locale: req.locale,
    })
  }
}

Rich Text Lexical Changes

1. Data Structure Change: Unpopulated lexical relationship, link, and upload nodes now save the relationTo document ID under value instead of value.id. This matches the behavior of core relationship fields but changes the shape of the saved JSON data.

2. Custom Features with Population: If you have custom features that add their own population promises, you need to rework them. The populationPromises function no longer accepts promises as a return value. Instead, it expects you to mutate the promises array which is passed through, similar to how it works in core:

// Before
populationPromises: ({ nodes }) => {
  return nodes.map(node => fetchSomething(node));
}

// After
populationPromises: ({ nodes, promises }) => {
  nodes.forEach(node => {
    promises.push(fetchSomething(node));
  });
}

Upgrade Recommendations

This beta release contains breaking changes that require code modifications. We recommend:

1. Review Breaking Changes: Carefully read the migration guide to understand the changes to request handling and richtext-lexical data structure.

2. Update Custom Handlers: If you have custom handlers, update them to use the new utilities for data, file, and locale handling.

3. Test Rich Text Content: If you use the richtext-lexical editor, test your content thoroughly after upgrading, especially if you have custom features with population logic.

4. Development Environment First: Apply this update in a development environment before deploying to production to ensure all your custom code works with the changes.

5. Update Dependencies: Make sure to update all Payload-related packages to the same version to avoid compatibility issues.

Bug Fixes

Critical Fixes

• Fixed issues with creating the first user in the system
• Fixed PostgreSQL UUID handling in the Postgres database adapter
• Fixed type collection config missing dbName

Rich Text Editor Fixes

• Fixed empty URL field validation in the link drawer
• Fixed block node nested fields validation, resolving a previously skipped e2e test suite
• Fixed Heading feature where enabledHeadingSizes was not being properly applied
• Fixed incorrect value for empty preferences passed into buildStateFromSchema

New Features

Rich Text Editor Improvements

• Reworked Population Behavior: The richtext-lexical editor now has improved population behavior and better node typing
• Field Hooks: Rich text adapters can now hook into field hooks, providing more customization options
• Loading Indicators: Added loading indicators while block nodes are loading in the richtext editor
• Field Validation: Added support for passing document preferences to field validate functions with improved types
• Horizontal Rule Feature: Added missing HorizontalRuleFeature export

Request Handling Utilities

• Added new utilities addDataAndFileToRequest and addLocalesToRequest to replace the deprecated getDataAndFile and getLocales functions in createPayloadRequest

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Performance Optimizations

• Improved richtext-lexical node typing which should result in better editor performance
• Enhanced field validation with better type checking
• Optimized block node loading with visual indicators to improve perceived performance

Impact Summary

This beta release brings significant improvements to the richtext-lexical editor and fixes several critical issues, but includes breaking changes that require developer attention. The changes to request handling in custom handlers and richtext data structure will require code updates for most projects using these features.

The richtext editor improvements provide better typing, validation, and user experience with loading indicators and fixed heading controls. System administrators will benefit from fixes to first user creation and PostgreSQL UUID handling.

While this is still a beta release, the breaking changes are substantial enough that developers should plan for dedicated time to update their code and test thoroughly before upgrading production environments. The provided migration guide offers clear examples of how to adapt to the new patterns.

Full Release Notes

// ❌ Before
{
  path: '/whoami/:parameter',
  method: 'post',
  handler: async (req) => {
    return Response.json({
      name: req.data.name, // data will be undefined
      // locales will be undefined
      fallbackLocale: req.fallbackLocale,
      locale: req.locale,
    })
  }
} 

// ✅ After
import { addDataAndFileToRequest } from '@payloadcms/next/utilities'
import { addLocalesToRequest } from '@payloadcms/next/utilities'

{
  path: '/whoami/:parameter',
  method: 'post',
  handler: async (req) => {
    // mutates req, must be awaited
    await addDataAndFileToRequest(req)
    
    // mutates req
    addLocalesToRequest(req)
	  
    return Response.json({
      name: req.data.name, // data is now available
      fallbackLocale: req.fallbackLocale, // locales available
      locale: req.locale,
    })
  }
}