Payload CMS Release: 3.0.0-beta.111

TL;DR

PayloadCMS v3.0.0-beta.111: Breaking Changes and Important Fixes

This release introduces significant breaking changes to database column naming conventions and Next.js/React compatibility. It includes critical fixes for database operations, UI improvements, and template updates. Developers using SQLite or PostgreSQL databases need to migrate their column names, and Next.js applications require type updates for params and searchParams.

Highlight of the Release

• Breaking change: Database column names for select and radio fields now use snake_case instead of camelCase
• Breaking change: Updated minimum supported versions to Next.js 15.0.0-canary.173 and React 19.0.0-rc
• Fixed UI crashes when editing documents with deleted uploads
• Fixed admin.allowCreate property behavior in upload fields
• UI fields now excluded from bulk edit by default (configurable)
• Fixed join relation names for camelCase relationships

Migration Guide

Migrating to v3.0.0-beta.111

Database Column Names (SQLite/PostgreSQL)

If you're using SQLite or PostgreSQL and have select (not hasMany: true) or radio fields with camelCase names, you'll need to migrate your database columns:

1. Generate a new migration:

   pnpm payload migrate:create
   

2. Select "rename column" for each affected column. Drizzle will handle the migration.

For example, a field named selectReadOnly will now be mapped to the database column select_read_only instead of "selectReadOnly".

Next.js and React Updates

Update your Next.js and React dependencies to the minimum supported versions:

• Next.js 15.0.0-canary.173
• React 19.0.0-rc-3edc000d-20240926

Update your types in app/(payload)/admin/[[...segments]]/page.tsx and app/(payload)/admin/[[...segments]]/not-found.tsx:

- type Args = {
-   params: {
-     segments: string[]
-   }
-   searchParams: {
-     [key: string]: string | string[]
-   }
- }

+ type Args = {
+   params: Promise<{
+     segments: string[]
+   }>
+   searchParams: Promise<{
+     [key: string]: string | string[]
+   }>
+ }

UI Fields in Bulk Edit

UI fields are now excluded from bulk edit by default. If you need to include them, add:

admin: {
  disableBulkEdit: false
}

Upgrade Recommendations

This release contains breaking changes that require manual intervention. We recommend:

1. For Database Users: Create and run migrations to rename your database columns from camelCase to snake_case for select and radio fields.

2. For Next.js Users: Update your Next.js and React dependencies and modify your type definitions for params and searchParams.

3. For All Users: Test your application thoroughly after upgrading, especially if you're using select/radio fields or Next.js integration.

The upgrade is recommended for all users to benefit from the numerous bug fixes and improvements, but plan for the necessary migration work, especially if you're using SQLite or PostgreSQL databases.

Bug Fixes

Database Fixes

• Fixed join relation names: Resolved an issue where join fields on relationships with camelCase names would cause errors from Drizzle due to mismatched relation names.
• Fixed row/collapsible inside localized fields: Addressed issues with row and collapsible fields inside localized fields in Drizzle.
• Fixed missing types for db.pool: Moved @types/pg from devDependencies to dependencies to ensure proper typing in installed projects.

UI Improvements

• Fixed admin.allowCreate in upload fields: The admin.allowCreate property now correctly controls the ability to create new uploads from the UI. When set to false, the option to create a new upload disappears.
• Fixed UI crashes with deleted uploads: Resolved an issue where the UI would crash when editing a document with a deleted upload.
• UI fields in bulk edit: UI fields are now excluded by default from the bulk edit view fields options. This can be overridden with admin: { disableBulkEdit: false }.

Template Fixes

• Fixed drafts in website template: Resolved an issue where drafts were not being unpublished in the frontend of the website template.
• Fixed dark/light mode: Corrected issues with dark and light mode not working correctly on the website template's header.
• Added no search results text: Added missing text for when no search results are found in the website template search page.
• Fixed static generation: Resolved issues with static generation from incorrect params.
• Added force-static to pages and posts: Improved static generation for pages and posts.

Other Fixes

• Fixed SEO plugin: The SEO plugin now correctly respects serverURL and API routes configuration.
• Fixed CommonJS withPayload export: Properly resolves CJS withPayload export for CommonJS imports using require.
• Fixed current published version label: Added parent to the getLatestVersion query to fix version label display.
• Safely checks user within useEffect: Improved user checking within useEffect to prevent errors.

New Features

Next.js and React Updates

The minimum supported versions have been updated to:

• Next.js 15.0.0-canary.173
• React 19.0.0-rc-3edc000d-20240926

This update brings the latest features and improvements from these frameworks to PayloadCMS projects.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Database Performance

The change from camelCase to snake_case for database column names in select and radio fields improves consistency with database best practices and may lead to better performance in some database operations.

Template Optimizations

Several template fixes and improvements have been made that can lead to better performance:

• Added force-static to pages and posts for improved static generation
• Fixed static generation from incorrect params
• Removed lock from website template to prevent dependency checker errors

Impact Summary

This release introduces significant changes to PayloadCMS, particularly for database operations and Next.js integration. The switch from camelCase to snake_case for database column names in select and radio fields improves database consistency but requires migration for existing projects. The update to Next.js 15 and React 19 brings the latest features but requires type updates.

The release also includes numerous bug fixes that improve stability and user experience, such as fixing UI crashes with deleted uploads, properly handling admin.allowCreate in upload fields, and excluding UI fields from bulk edit by default.

Template users will benefit from fixes to drafts, dark/light mode, search results, and static generation. The SEO plugin now correctly respects serverURL and API routes configuration.

Overall, this release enhances stability, fixes critical bugs, and prepares PayloadCMS for future compatibility with Next.js and React, though it requires some migration work for existing projects.

Full Release Notes