Payload CMS Release: 3.0.0-beta.33

TL;DR

Payload CMS v3.0.0-beta.34 brings significant updates to the Lexical rich text editor, improves Next.js compatibility, enhances accessibility, and fixes numerous bugs. This release includes breaking changes related to minimum Next.js version requirements, plugin exports, and configuration structure changes. The update focuses on improving developer experience with better TypeScript support, more consistent APIs, and enhanced UI components.

Highlight of the Release

• Upgraded Lexical rich text editor to version 0.15.0 with improved UX and positioning options
• Improved accessibility for multiselect relationship fields
• Enhanced TypeScript support with typed i18n and better error handling
• Added new plugin positioning options for rich text editor
• Fixed numerous bugs in database queries, file uploads, and UI components
• Consolidated admin configuration properties for better developer experience

Migration Guide

Upgrading to Next.js 14.3.0-canary.68+

This release requires Next.js 14.3.0-canary.68 or higher due to the migration from experimental.serverComponentsExternalPackages to experimental.serverExternalPackages. Update your Next.js version in your package.json:

npm install [email protected] --save
# or
yarn add [email protected]
# or
pnpm add [email protected]

Plugin Import Changes

All plugins now use named exports with consistent naming. 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'

Admin Configuration Changes

Several admin configuration properties have been consolidated or renamed:

1. Replace admin.favicon with admin.icons:

// Before
admin: {
  favicon: '/favicon.ico',
}

// Now
admin: {
  icons: {
    favicon: '/favicon.ico',
    // other icons can be specified here
  },
}

2. Replace admin.meta.ogImage with admin.meta.openGraph.images:

// Before
admin: {
  meta: {
    ogImage: '/og-image.jpg',
  }
}

// Now
admin: {
  meta: {
    openGraph: {
      images: ['/og-image.jpg'],
    }
  }
}

3. Consolidate admin.logoutRoute and admin.inactivityRoute into admin.routes:

// Before
admin: {
  logoutRoute: '/custom-logout',
  inactivityRoute: '/custom-inactivity',
}

// Now
admin: {
  routes: {
    logout: '/custom-logout',
    inactivity: '/custom-inactivity',
  }
}

Custom Component Changes

If you're using custom components, note these changes:

1. Move admin.description custom components to appropriate locations:

   • For Globals: admin.components.elements.Description
   • For Collections: admin.components.edit.Description
   • For Fields: field.admin.components.Description

2. Move field.label custom components in Collapsible fields to field.admin.components.RowLabel

Lexical Rich Text Editor Changes

If you're using the Lexical rich text editor:

1. Update your code if you're using Lexical APIs directly, as this release upgrades Lexical from 0.14.5 to 0.15.0.

2. If you have custom Lexical features, note these API changes:

   • floatingSelectToolbar has been changed to toolbarInline
   • slashMenu.dynamicOptions and slashMenu.options have been changed to slashMenu.groups and slashMenu.dynamicGroups
   • toolbarFixed.sections is now toolbarFixed.groups
   • Slash menu group options and toolbar group entries have both been renamed to items
   • Toolbar group item onClick has been renamed to onSelect
   • The default inline toolbar has been extracted into an InlineToolbarFeature

3. If you're using custom link fields in the Lexical editor:

// Before
LinkFeature({
  fields: [
    {
      name: 'rel',
      label: 'Rel Attribute',
      type: 'select',
      hasMany: true,
      options: ['noopener', 'noreferrer', 'nofollow'],
      admin: {
        description: 'The rel attribute defines the relationship between a linked resource and the current document.',
      },
    },
  ],
}),

// Now
LinkFeature({
  fields: ({ defaultFields }) => [
    ...defaultFields,
    {
      name: 'rel',
      label: 'Rel Attribute',
      type: 'select',
      hasMany: true,
      options: ['noopener', 'noreferrer', 'nofollow'],
      admin: {
        description: 'The rel attribute defines the relationship between a linked resource and the current document.',
      },
    },
  ],
}),

Other Breaking Changes

1. The staticOptions config on uploads has been removed as it was unused.

2. The sanitizeFields function is now async, which may affect your code if you're using it directly.

3. The initPage export has been removed from the barrel file in the Next.js package. Import it directly from its module instead.

Upgrade Recommendations

This is a beta release with significant breaking changes, so we recommend:

1. For Production Applications: Wait for the stable 3.0.0 release unless you specifically need features or fixes in this beta.

2. For Development/Testing: This is a good time to test your application with the new beta to identify and address any breaking changes before the stable release.

3. For New Projects: You can start with this beta version as it includes many improvements and fixes.

When upgrading:

1. Update your Next.js version to 14.3.0-canary.68 or higher
2. Update all Payload packages to v3.0.0-beta.34
3. Follow the migration guide to address breaking changes
4. Test thoroughly, especially if you're using custom Lexical features or plugins

If you encounter issues, check the GitHub issues or report new ones.

Bug Fixes

Database and Query Fixes

• Fixed PostgreSQL issues with UUID custom DB names
• Fixed PostgreSQL query issues with LIKE operator on ID columns
• Fixed PostgreSQL filter with ID not_in AND queries
• Fixed issues with GraphQL locale cascading through relationships

UI and Form Fixes

• Fixed issue with React Select menu being hidden behind Lexical fixed toolbar
• Fixed incorrect stepnav breadcrumbs after selecting existing upload
• Fixed issue with conditions throwing errors breaking form state
• Fixed issue with multiselect relationship fields crashing when using space key
• Fixed issue with save button not being properly enabled after form modification
• Fixed issue with collection labels with multiple locales showing incorrectly

Rich Text Editor Fixes

• Fixed upload, relationship and block node insertion failures
• Fixed autoLink node styles not being inherited from original text node on creation
• Fixed floating link editor not properly hiding when selection is not a range
• Fixed text selection issues within relationship and upload node components

Other Fixes

• Fixed issue with safely accessing cookie header for uploads
• Fixed loader support for TypeScript paths and server-only modules
• Fixed issue with logout-inactivity route 404ing
• Fixed issue with form data handling on Vercel
• Fixed issue with bulk publishing from collection list

New Features

Rich Text Editor Improvements

• Upgraded Lexical rich text editor from 0.14.5 to 0.15.0
• Added new aboveContainer and belowContainer plugin positioning options
• Implemented rootFeatures prop for Lexical editor
• Improved draggable block indicator style and animations
• Enhanced fixed toolbar wrapping for small screen sizes
• Fixed various selection and focus issues in the editor

UI and Accessibility Enhancements

• Added toggle functionality for sortable arrays and blocks
• Improved multiselect relationship fields for better accessibility
• Added translations for API view and select components
• Exported PNG favicons for better cross-browser compatibility
• Improved crop rendering in thumbnails

Developer Experience

• Added typed i18n support for better type safety
• Implemented GraphQL schema generation
• Added support for client components and extra RSC props for custom views
• Added support for server-only module in the Payload loader
• Improved TypeScript support throughout the codebase

Security Updates

Security Improvements

• Fixed issue with non-admin users potentially accessing admin routes
• Improved validation to ensure user slug is an auth-enabled collection
• Enhanced permissions handling for nested documents
• Improved version permissions checking
• Added proper conditional rendering of versions tab based on read access

Performance Improvements

Performance Optimizations

• Improved loader performance by removing unnecessary module resolution for client files
• Optimized PostgreSQL queries by sanitizing LIKE operators for number or UUID fields
• Reduced unnecessary editor updates in Lexical rich text editor
• Improved TypeScript performance by loosening type for ClientTranslationsObject
• Enhanced form validation performance by preventing unnecessary re-renders

Impact Summary

Payload CMS v3.0.0-beta.34 represents a significant step toward the stable 3.0.0 release with substantial improvements to the rich text editing experience, better TypeScript support, and enhanced Next.js integration. The upgrade to Lexical 0.15.0 brings improved editor performance and reliability, while the consolidation of admin configuration properties creates a more consistent developer experience.

This release includes several breaking changes that require attention during upgrade, particularly around minimum Next.js version requirements, plugin import patterns, and configuration structure changes. The migration to named exports for plugins and the restructuring of admin configuration properties will require code changes, but these changes create a more consistent and maintainable API.

For content editors, the improvements to the Lexical rich text editor provide a better editing experience with enhanced UI for draggable blocks, better toolbar positioning, and improved handling of complex content like links and uploads. The accessibility improvements to multiselect relationship fields and better form validation enhance the overall usability of the admin interface.

Developers will benefit from improved TypeScript support, better error handling, and more consistent APIs. The addition of typed i18n support and better GraphQL schema generation improves type safety and developer productivity.

Overall, this release balances introducing new features with fixing bugs and improving the developer and user experience, making it a worthwhile upgrade for those working with Payload CMS, especially if they're already on the v3 beta track.

Full Release Notes