Payload CMS Release: 3.0.0-beta.121

TL;DR

Payload CMS v3.0.0-beta.121 introduces significant enhancements including a new jobs queue system, field selection optimization, and improved custom views accessibility. This release also fixes several UI issues, improves MongoDB relationship handling, and includes important breaking changes to the search plugin and custom views behavior.

Highlight of the Release

• New jobs queue system for background processing tasks
• Field selection optimization with the new select property
• Custom views are now public by default with improved access control
• Added defaultPopulate property to optimize relationship data retrieval
• Ability to prevent creating new documents from join fields

Migration Guide

Breaking Changes in Search Plugin with Localization

If you have a localized Payload config and are using the plugin-search, the plugin will now automatically localize the title field that it injects. This may lead to data loss if you're relying on the previous behavior.

Migration Steps:

1. To opt out of this new behavior, pass localize: false to the plugin options:

import { searchPlugin } from '@payloadcms/plugin-search'

export default buildConfig({
  plugins: [
    searchPlugin({
      // Opt out of automatic title field localization
      localize: false,
      collections: ['posts', 'pages'],
    }),
  ],
})

Custom Views Now Public by Default

Custom views are now public by default, which means they are accessible to non-authenticated users unless specifically configured otherwise.

Migration Steps:

1. Review your custom views and ensure they have appropriate access control if they contain sensitive information
2. For views that should be protected, update your configuration to explicitly require authentication

Payload Cloud Plugin Import Path

If you're using the Payload Cloud plugin, update your import statement:

Before:

import { payloadCloud } from '@payloadcms/payload-cloud'

After:

import { payloadCloudPlugin } from '@payloadcms/payload-cloud'

Upgrade Recommendations

This beta release contains significant new features and important bug fixes, making it a valuable upgrade for most Payload CMS users. However, it also includes breaking changes that require attention.

Who should upgrade immediately:

• Developers who need the new jobs queue functionality
• Projects experiencing issues with MongoDB relationship handling
• Anyone who would benefit from the field selection optimization features
• Teams experiencing UI issues with bulk uploads or text area fields

Caution for:

• Projects using the search plugin with localization enabled (requires configuration adjustment)
• Applications with custom views that may need access control review

Upgrade Steps:

1. Update your package.json to reference the new version
2. Review the breaking changes section and apply necessary migrations
3. Test thoroughly, especially if you're using the search plugin with localization or have custom views
4. Take advantage of the new features like jobs queue and field selection optimization

Bug Fixes

UI Improvements

• Fixed missing localization label on text area fields
• Fixed broken buttons in the bulk upload drawer
• Fixed performance issues in bulk upload
• Fixed sanitization of limit values for preferences

MongoDB Fixes

• Ensured relationships are stored as ObjectID even when nested in arrays or blocks
• Fixed joins with singular collection names by using the collection name from the driver directly
• Fixed issue with passing string limit value from user preferences to MongoDB's .aggregate function

Search Plugin Localization

• Fixed an issue where the search plugin was incorrectly retrieving all locales instead of just the locale of the parent document being updated

Documentation Fixes

• Fixed unformatted table in form builder number field documentation
• Fixed dead links in documentation
• Fixed docs-wide spelling errors and formatting issues
• Updated Payload Cloud plugin documentation to match current implementation

New Features

Jobs Queue System

A comprehensive jobs queue system has been added to Payload, allowing for background processing tasks. This feature includes:

• Ability to define workflows and tasks in your configuration
• Type-safe job creation with payload.createJob
• Support for retries and dynamic imports
• Bin script for running jobs

Field Selection Optimization

The new select property allows you to specify field projections for local and REST API calls, optimizing database queries and reducing payload sizes:

• Generate types for the select property
• Infer return types based on include/exclude patterns
• Support for deep fields and localization

Default Populate for Collections

Added defaultPopulate property to collection configs that allows specifying which fields to select when the collection is populated from another document:

export const Pages: CollectionConfig<'pages'> = {
  slug: 'pages',
  defaultPopulate: {
    slug: true,
  },
  fields: [
    {
      name: 'slug',
      type: 'text',
      required: true,
    },
  ],
}

Prevent Create New for Joins

Added the ability to prevent creating new documents from the admin UI in a join field:

• New allowCreate admin property for join fields
• By default, UI will never allow create when the current document being edited does not yet have an ID
• Improves workflow when creating relationships

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

API Response Optimization

The new select fields feature allows for significant performance improvements by reducing the payload size of API responses and making database queries more efficient. This is particularly valuable for large documents or when working with relationships.

Relationship Data Optimization

The new defaultPopulate property allows developers to specify exactly which fields should be retrieved when populating relationships, avoiding unnecessary data transfer when only specific fields are needed.

Bulk Upload Performance

Performance improvements have been made to the bulk upload functionality in the admin UI, making the process smoother and more efficient.

Impact Summary

This release represents a significant step forward for Payload CMS with the introduction of several powerful features that enhance both developer experience and application performance.

The new jobs queue system enables background processing capabilities, allowing developers to implement complex workflows and tasks that run asynchronously. This is particularly valuable for operations that are resource-intensive or need to be executed on a schedule.

The field selection optimization feature addresses a common performance concern by allowing developers to specify exactly which fields should be returned in API responses, reducing payload sizes and database load. Similarly, the defaultPopulate property provides fine-grained control over relationship data retrieval.

UI improvements fix several issues with the admin interface, particularly around bulk uploads and localization, enhancing the content editing experience. The MongoDB relationship handling fixes ensure data consistency and proper operation with various collection naming conventions.

The breaking changes to custom views and the search plugin require attention during upgrades but ultimately provide more intuitive behavior and better access control. Overall, this release balances new capabilities with important refinements to existing functionality.

Full Release Notes