Payload CMS Release: 3.1.0

TL;DR

Payload CMS v3.1.0 brings significant enhancements to the rich text editor (Lexical), improved server component handling, and fixes for critical UI and database issues. This release focuses on developer experience with better TypeScript support, more customization options for the rich text editor, and improved migration commands. Users will benefit from fixed UI issues, better document handling with non-standard IDs, and enhanced live preview functionality.

Highlight of the Release

• Enhanced rich text editor with improved block handling and selection management
• Fixed critical UI issues in the admin panel
• Better TypeScript support with fixed collection types
• Improved PostgreSQL database adapter with fixes for joins with versions and hasMany relationships
• New migration command flags for better developer workflow
• Fixed client-side live preview for array fields

Migration Guide

Updating to v3.1.0

This release doesn't contain breaking changes that require specific migration steps. You can update your Payload CMS installation from v3.0.x to v3.1.0 by updating your package dependencies:

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

TypeScript Users

If you're using TypeScript and accessing payload.collections directly in your code, you might benefit from the fixed type definitions. The type has been changed from:

collections: {
  [slug: CollectionSlug]: Collection
} = {}

to:

collections: Record<CollectionSlug, Collection> = {}

This provides better type inference when accessing collection objects.

Upgrade Recommendations

We recommend all users upgrade to v3.1.0 as it contains important bug fixes and quality-of-life improvements without introducing breaking changes.

• Priority: Medium
• Effort: Low (standard package update)
• Risk: Low (no breaking changes)

This release is particularly valuable for:

1. Users experiencing issues with the rich text editor, especially with slash menu behavior or text formatting
2. PostgreSQL users with complex relationships using versions and hasMany fields
3. Developers using custom providers as server components
4. Anyone experiencing UI issues with sidebar groups or array fields
5. Next.js 15.0.3 users

The update process should be straightforward and doesn't require any code changes for most users.

Bug Fixes

Admin UI Fixes

• Sidebar Groups: Fixed error when collapsing sidebar groups.
• Blocks Drawer Toggler: Added missing disabled attribute to blocks drawer toggler when update access control is set to false.
• Server Components: Fixed stale server components when array rows are moved, ensuring proper re-rendering.
• Document Loading: Fixed issue with loading documents that have non-standard IDs, properly decoding URL parameters.

Rich Text Editor Fixes

• Slash Menu Behavior: Fixed issue where slash menu query wouldn't disappear after selecting a slash menu item.
• Text Formatting Preservation: Fixed preservation of indent and text-align attributes when converting between Lexical and HTML formats.
• Block Collapsed State: Fixed error when changing block collapsed state in rare cases.
• Slash Menu Selection: Fixed bug where slash menu from + button did not trigger item select action.

Database and API Fixes

• PostgreSQL Joins: Fixed issues with joins involving versions and hasMany relationships in the PostgreSQL adapter.
• Collection Types: Fixed invalid payload.collections type definition for better TypeScript support.

Next.js Integration

• Server Props Threading: Fixed issue where server props weren't being passed to custom providers when defined as server components.
• Next.js 15.0.3 Compatibility: Added compatibility for turbopack warnings patch with Next.js 15.0.3.

Other Fixes

• Admin Panel Access: Fixed error when opening admin panel without any permissions.
• Live Preview: Fixed issue where client-side live preview couldn't clear all array rows.
• Website Template: Fixed breaking change in website template by renaming hero image to jpg format.

New Features

Rich Text Editor Enhancements

• More Powerful Custom Block RSCs: Custom Lexical block & inline block components now re-render when fields drawer is saved, ensuring React Server Components receive updated values without requiring client components.
• Customizable Toolbar Groups: Added ability to customize maxActiveItems for toolbar groups, useful for cases where multiple items can be active simultaneously.
• Exported Lexical Drawer Hooks: Made drawer hooks available for external use, enabling more customization options.

Migration Command Improvements

• Skip Empty Flag: Added --skip-empty flag to migrate:create command to bypass the empty migration file prompt.
• Force Accept Warning Flag: Added --force-accept-warning flag to migrate:fresh command to bypass the database drop confirmation prompt.

Template Updates

• Website Template Enhancements: Updated website template styles and added a new home hero image.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Database Query Optimization

• Reduced Join Query Overhead: The PostgreSQL adapter now avoids unnecessary joinQuery overhead when not needed for the current operation. Joins are now only supported for specific operations (find, findOne, and queryDrafts), resulting in more efficient database queries.

TypeScript Improvements

• Stricter Type Checking: Enabled strict: true in the richtext-lexical package, building on previous work that enabled noImplicitAny and strictNullChecks. This helps catch potential issues at compile time rather than runtime.

Server Component Handling

• Improved Re-rendering: Enhanced server component handling to prevent stale components when array rows are moved, adding, or deleting rows, ensuring UI stays in sync with data changes.

Impact Summary

Payload CMS v3.1.0 delivers a substantial update focused on enhancing developer experience and fixing critical issues across the platform. The rich text editor (Lexical) receives significant improvements with better custom block handling, selection management, and text formatting preservation. These changes make content editing more reliable and intuitive.

Database operations are more efficient with optimized PostgreSQL joins, particularly benefiting complex data models using versions and hasMany relationships. TypeScript developers will appreciate the fixed collection types and stricter type checking in the richtext-lexical package.

The admin UI experience is improved with fixes for sidebar groups, blocks drawer togglers, and server component rendering. These changes ensure a more stable and predictable interface for content editors and administrators.

For developers, new migration command flags provide more flexibility in workflow automation, and better Next.js integration ensures compatibility with the latest versions. The ability to customize rich text toolbar groups and access drawer hooks opens up new possibilities for tailored editing experiences.

Overall, this release represents a solid iteration that addresses user feedback and pain points without introducing breaking changes, making it a recommended upgrade for all Payload CMS users.

Full Release Notes