Payload CMS Release: 3.0.0-beta.60

TL;DR

PayloadCMS v3.0.0-beta.60: Admin UI Color Refresh & API Improvements

This beta release brings significant updates to PayloadCMS with a refreshed admin panel color palette, improved API utilities, and several plugin enhancements. The color system has been redesigned for better consistency between light and dark modes, while key utility functions are now properly exported from the main package. The search plugin has been updated with a more flexible API pattern, and several bug fixes address GraphQL concurrency issues and UI positioning problems.

Highlight of the Release

• Refreshed admin panel color palette with better consistency between light and dark modes
• Key utility functions now properly exported from main package instead of UI internals
• Search plugin API updated to use function-based fields pattern for better flexibility
• Fixed GraphQL query concurrency issues
• Exposed Azure storage client for direct access
• Replaced qs with qs-esm for smaller bundle size and better ESM support
• Added website template to Create Payload App

Migration Guide

Updating Import Paths for Utility Functions

If you were previously importing any of these utilities:

import { getSiblingData, getDataByPath, reduceFieldsToValues } from '@payloadcms/ui/forms/Form'
import { unflatten } from '@payloadcms/ui/utilities'

Update your imports to:

import { getSiblingData, getDataByPath, reduceFieldsToValues, unflatten } from 'payload/shared'

Updating Search Plugin Configuration

If you were using the search plugin with field overrides:

// Before
searchPlugin({
  searchOverrides: {
    slug: 'search-results',
    fields: [
      {
        name: 'excerpt',
        type: 'textarea',
        admin: {
          position: 'sidebar',
        },
      },
    ]
  },
}),

Update to the new function-based pattern:

// After
searchPlugin({
  searchOverrides: {
    slug: 'search-results',
    fields: ({ defaultFields }) => [
      ...defaultFields,
      {
        name: 'excerpt',
        type: 'textarea',
        admin: {
          position: 'sidebar',
        },
      },
    ]
  },
}),

Handling Color Palette Changes

If you're using any of Payload's color variables in your custom CSS, you may need to adjust your styling to account for the new color values. The following color palettes have changed:

• --theme-success-*
• --theme-error-*
• --theme-warning-*
• --color-success-*
• --color-error-*
• --color-warning-*
• --color-blue-*

Review your custom styling and make adjustments as needed to maintain proper styling and accessibility.

Upgrade Recommendations

This beta release contains several breaking changes that affect color variables and API imports. We recommend:

1. For developers using utility functions: Update your import paths as outlined in the migration guide.

2. For developers using the search plugin: Update your configuration to use the new function-based fields pattern.

3. For projects with custom styling: Review any custom CSS that uses Payload's color variables and adjust as needed.

4. For all users: Test thoroughly in your development environment before deploying to production, as this is still a beta release.

The changes in this release improve the consistency and maintainability of the codebase, so upgrading is recommended despite the breaking changes. The benefits of better color consistency, improved API structure, and bug fixes outweigh the migration effort for most projects.

Bug Fixes

GraphQL Query Concurrency Issues

Fixed issues with GraphQL query concurrency that could cause race conditions and unexpected behavior in high-traffic scenarios.

Field Tooltip Positioning

Resolved a bug where tooltips for fields rendered outside of RenderFields were not positioned correctly, improving the UI experience for custom field layouts.

Plugin Field Type Definitions

Fixed type definitions in the redirects and form-builder plugins to make the fields property properly optional in overrides, improving TypeScript support.

New Features

Admin UI Color Refresh

The admin panel color palette has been completely updated to provide better consistency between dark and light modes. The new palette ensures contrast values align better with the theme-elevation contrasts, improving accessibility and visual coherence throughout the interface. Toast components have also been adjusted to better match light/dark mode.

Improved API Utilities

Key utility functions (getSiblingData, getDataByPath, reduceFieldsToValues, and unflatten) are now properly exported from the main Payload package via payload/shared. This makes these utilities available outside of React environments and provides a more stable API surface.

Search Plugin Enhancements

The search plugin now uses a function-based pattern for field overrides, aligning with other plugins and providing more flexibility. This allows developers to easily extend the default fields rather than replacing them entirely.

Azure Storage Client Access

The Azure storage plugin now exposes its storage client, allowing developers to reuse the client for other Azure blob storage operations outside of Payload's file handling.

Website Template in Create Payload App

The website template has been added to the Create Payload App (CPA) tool, making it easier to start new projects with this template. The CPA tool has also been improved with better .env handling.

Bundle Size Optimization

Replaced the qs package with qs-esm, a more efficient ESM-only alternative that reduces bundle size from 11kb to 4.2kb and eliminates unnecessary polyfills and dependencies.

Security Updates

No specific security fixes were included in this release.

Performance Improvements

Smaller Bundle Size

Replaced the qs package with qs-esm, reducing the bundle size from 11kb to 4.2kb and eliminating 14 unnecessary dependencies. This change improves load times and reduces the overall footprint of applications using PayloadCMS.

Lexical Rich Text Editor Optimization

Removed unused json-schema dependency from the Lexical rich text editor package, making it smaller and more efficient. Only @types/json-schema is now required as a development dependency.

Impact Summary

This beta release brings significant improvements to PayloadCMS's admin UI with a refreshed color palette that provides better consistency between light and dark modes. The export of key utility functions from the main package improves the developer experience by providing a more stable API surface.

The search plugin's updated API pattern aligns with other plugins and provides more flexibility for extending default fields. Several bug fixes address GraphQL concurrency issues and UI positioning problems, improving stability and user experience.

The breaking changes in this release are focused on API improvements and color system updates, requiring some migration effort but providing long-term benefits in terms of consistency and maintainability. The addition of the website template to Create Payload App and the exposure of the Azure storage client provide more options and flexibility for developers.

Overall, this release represents a significant step forward in PayloadCMS's UI consistency, developer experience, and plugin ecosystem, making it a worthwhile upgrade despite the breaking changes.

Full Release Notes