Payload CMS Release: 3.0.0-beta.104

TL;DR

PayloadCMS v3.0.0-beta.104 brings significant improvements to the developer and content editor experience with new features like document drawer controls for inline creation, duplication, and deletion of documents, improved field width handling in rows, and better support for JSON field operators in Drizzle. This release also includes important bug fixes and a breaking change that renames BlockField types to the more accurate BlocksField to better align with the field's plural nature.

Highlight of the Release

• Document drawer controls for inline creation, duplication, and deletion of documents
• Support for in and not_in operators on JSON fields in Drizzle
• Client field config now accessible in server components via clientField prop
• Fixed row field width handling for better UI layout
• Breaking change: renamed BlockField types to BlocksField for better semantic alignment

Migration Guide

Migrating from BlockField to BlocksField

If you were using the BlockField or related types in your applications, you'll need to update your imports to use the plural form instead:

Old (singular):

import type {
  BlockField,
  BlockFieldClient,
  BlockFieldValidation,
  BlockFieldDescriptionClientComponent,
  BlockFieldDescriptionServerComponent,
  BlockFieldErrorClientComponent,
  BlocksFieldErrorServerComponent,
  BlockFieldLabelClientComponent,
  BlockFieldLabelServerComponent,
} from 'payload'

New (plural):

import type {
  BlocksField,
  BlocksFieldClient,
  BlocksFieldValidation,
  BlocksFieldDescriptionClientComponent,
  BlocksFieldDescriptionServerComponent,
  BlocksFieldErrorClientComponent,
  BlocksFieldErrorServerComponent,
  BlocksFieldLabelClientComponent,
  BlocksFieldLabelServerComponent,
} from 'payload'

This change better aligns the type names with the actual field type, which is plural ("blocks").

Upgrade Recommendations

For Developers Using BlockField Types

If you're using BlockField types in your code, this is a breaking change that requires updating your imports to the new plural form (BlocksField). The upgrade is straightforward but necessary to maintain compatibility.

For All Users

For all other users, this upgrade is recommended as it brings significant UI improvements and workflow enhancements, particularly for content editors working with document relationships. The bug fixes for row field widths and array field labels also improve the overall user experience.

Since this is still a beta release, standard beta upgrade cautions apply - test thoroughly in a non-production environment before deploying to production.

Bug Fixes

Row Field Width

Fixed an issue where setting admin.width on fields inside rows, groups, or arrays wasn't working correctly. The solution implements a CSS variable --field-width that allows for proper width calculation with flex: 0 1 var(--field-width) and handles gaps correctly with flex-wrap: wrap.

Array Field Labels

Fixed a bug where singular labels were not being properly used for array field rows. The array field now correctly retrieves and displays the appropriate label format.

Vercel Postgres Adapter Naming

Fixed a casing mismatch between the defined value (camelCase) of Vercel's Postgres database adapter and the package name (kebab-case), resolving compatibility issues.

Website Template Media Directory

Updated the website template to correctly set the media staticDir to the public folder.

New Features

Document Drawer Controls

Content editors can now create, duplicate, and delete documents directly within document drawers without navigating away from their current context. This significantly improves the content editing workflow, especially when working with relationship fields where you can now perform these actions inline.

JSON Field Operators in Drizzle

Added support for in and not_in operators against JSON field filters in Drizzle. This brings PostgreSQL support in line with MongoDB, allowing queries like:

await payload.find({
  collection: 'posts',
  where: {
    'data.value': {
      in: ['12', '13', '14'],
    },
  },
})

Client Field Config for Server Components

Server components now receive the client field configuration through a new clientField prop, making it possible to render Payload field components from server components:

import { TextField } from '@payloadcms/ui'
import type { TextFieldServerComponent } from 'payload'

export const MyCustomServerField: TextFieldServerComponent = ({ clientField }) => {
  return <TextField field={clientField} />
}

Security Updates

No specific security fixes were included in this release.

Performance Improvements

The document drawer controls feature improves performance in content editing workflows by eliminating the need to navigate between pages to perform common document operations. This reduces page loads and context switching, resulting in a more efficient editing experience.

The fix for row field width handling also improves UI rendering performance by using CSS variables for width calculations instead of potentially expensive JavaScript operations.

Impact Summary

This release significantly enhances the content editing experience in PayloadCMS with the addition of document drawer controls that allow for inline document creation, duplication, and deletion without navigating away from the current context. This is particularly valuable for relationship fields and improves workflow efficiency.

The fix for row field width handling resolves a longstanding issue with field sizing in complex layouts, providing better control over the UI presentation. Developers will also benefit from improved type naming consistency with the BlocksField rename (though this is a breaking change requiring code updates) and the ability to use client field configurations in server components.

For database operations, the added support for in and not_in operators on JSON fields in Drizzle brings PostgreSQL functionality closer to parity with MongoDB, expanding the query capabilities for developers working with JSON data.

Overall, this release focuses on improving both developer and content editor experiences with thoughtful enhancements to the UI and API.

Full Release Notes