Payload CMS Release: 3.0.0-beta.123

TL;DR

Payload CMS v3.0.0-beta.123 brings a significant breaking change to the SEO plugin, now requiring a function-based approach for field customization. This release also includes important bug fixes for TypeScript return types, document locking with restricted user access, UI improvements for ReactSelect components, and fixes for unnamed tabs in MongoDB queries.

Highlight of the Release

• Breaking change in SEO plugin: field customization now uses a function-based approach
• Fixed TypeScript return type for findByID with strict: true
• Improved document locking with restricted user access
• Fixed UI issues with ReactSelect z-index and document locked modal width
• Better handling of unnamed tabs with select in MongoDB adapter

Migration Guide

Migrating the SEO Plugin

If you're using the SEO plugin, you'll need to update your code to use the new function-based approach for field customization:

Before:

seoPlugin({
  fieldOverrides: {
    title: {
      required: true,
    },
  },
  fields: [
    {
      name: 'customField',
      type: 'text',
    }
  ]
})

After:

seoPlugin({
  fields: ({ defaultFields }) => {
    const modifiedFields = defaultFields.map((field) => {
      // Override existing fields
      if ('name' in field && field.name === 'title') {
        return {
          ...field,
          required: true,
        }
      }
      return field
    })

    return [
      ...modifiedFields,
      // Add a new field
      {
        name: 'customField',
        type: 'text',
      },
    ]
  },
})

The key differences are:

1. fieldOverrides has been removed entirely
2. fields is now a function that receives defaultFields and returns an array
3. You must map over the default fields to modify them and include them in your return array
4. New fields are added to the return array alongside the modified default fields

Upgrade Recommendations

This release contains a breaking change to the SEO plugin, so if you're using this plugin, you should plan your upgrade carefully:

1. For SEO Plugin Users: This is a breaking change that requires code modifications. Review the migration guide and update your SEO plugin implementation before upgrading.

2. For All Other Users: This is a recommended upgrade that includes important bug fixes for TypeScript return types, document locking with restricted user access, and UI improvements.

Since this is still a beta release (v3.0.0-beta.123), it's advisable to test thoroughly in a non-production environment before deploying to production.

Bug Fixes

TypeScript and API Fixes

• Fixed findByID Return Type: Corrected the return type of findByID when strict: true / strictNullChecks: true is used, adding null to the return type only when disableErrors: true is passed.

• Fixed Document Locking with Restricted User Access: When read access is restricted on the users collection, restricted users would not have access to complete user data objects, only their IDs. This caused issues when determining document lock status. The fix now properly handles both cases, checking if the incoming user data is an object or just a string/number value.

• Fixed select with Unnamed Tabs: Improved handling of select for properties inside unnamed tabs using the MongoDB adapter. Also refactored traverseFields in Drizzle to reuse logic from groups/collapsible or rows if unnamed.

UI Fixes

• Increased z-index of ReactSelect: Fixed an issue where ReactSelect components were being hidden behind other elements by increasing their z-index.

• Fixed Document Locked Modal Width: Corrected an issue with overly large width on document locked modal content in Next.js.

Template Fixes

• Website Template: Fixed an error inside the populateAuthors hook in the website template.

Documentation Improvements

• Improved documentation about beforeSync in the search plugin to prevent confusion and save developer time.

New Features

SEO Plugin Improvements

The SEO plugin has been significantly improved with a new function-based approach for field customization:

• fieldOverrides has been removed
• fields is now a function that takes in defaultFields and expects an array of fields in return

This makes it much easier to override and extend existing fields or add new ones, bringing the plugin in line with patterns used in other Payload plugins.

Example of the new approach:

seoPlugin({
  fields: ({ defaultFields }) => {
    const modifiedFields = defaultFields.map((field) => {
      // Override existing fields
      if ('name' in field && field.name === 'title') {
        return {
          ...field,
          required: true,
        }
      }
      return field
    })

    return [
      ...modifiedFields,
      // Add a new field
      {
        name: 'ogTitle',
        type: 'text',
        label: 'og:title',
      },
    ]
  },
})

Additional improvements to the SEO plugin include:

• Fixed issues with localization labels not showing up on default fields
• Added ability to add before and after inputs to default fields

Security Updates

No security fixes were mentioned in this release.

Performance Improvements

No specific performance improvements were highlighted in this release. The changes were primarily focused on bug fixes, feature enhancements, and breaking changes to the SEO plugin.

Impact Summary

This release of Payload CMS (v3.0.0-beta.123) introduces a significant breaking change to the SEO plugin, moving from a configuration-based approach to a more flexible function-based approach for field customization. This change aligns the SEO plugin with patterns used in other Payload plugins and provides developers with more control over field customization.

The release also addresses several important bugs, including TypeScript return type corrections for findByID with strict mode, improved handling of document locking with restricted user access, and fixes for UI issues with ReactSelect components and document locked modals.

For developers using the SEO plugin, this update requires code changes to adapt to the new function-based approach. The migration is straightforward but mandatory. For other users, this release provides valuable bug fixes and improvements without requiring significant changes to existing code.

Overall, this beta release continues to refine Payload CMS as it moves toward a stable v3.0.0 release, with improvements focused on developer experience, TypeScript accuracy, and UI refinements.

Full Release Notes