Payload CMS Release: 3.7.0

TL;DR

Payload CMS v3.7.0 introduces several new features including the ability to hide entities from the nav sidebar without disabling routes, customizable code editor heights, and improved REST/GraphQL performance with pagination: false. Bug fixes address issues with username validation, rich text truncation, and form state rendering. The release also includes UI refactors, documentation improvements, and template updates.

Highlight of the Release

• Hide entities from nav sidebar/dashboard without disabling routes using admin.group: false
• Improved performance for large collections with pagination: false option in REST/GraphQL
• Support for loading predefined migrations from proper exports
• Fixed rich text truncation when displayed within joins fields
• Username validation now allows all special characters
• Fixed form rendering for conditional fields to eliminate 'blinking' effect

Migration Guide

Upgrading to v3.7.0

This release doesn't contain breaking changes, so upgrading from v3.6.0 should be straightforward:

1. Update your Payload dependency:

   npm install [email protected]
   # or
   yarn add [email protected]
   # or
   pnpm add [email protected]
   

2. If you're using the admin.hidden property to hide entities from the sidebar but still want to keep their routes accessible, consider switching to admin.group: false for better semantics.

3. For large collections where you don't need pagination information, consider using the new pagination: false option in your REST or GraphQL queries for improved performance.

4. If you're using the nested-docs plugin and have experienced issues with parent document publishing affecting child documents, this release fixes that issue.

Upgrade Recommendations

We recommend upgrading to v3.7.0 as it includes several quality-of-life improvements and bug fixes without introducing breaking changes. The performance improvements for large collections and the ability to hide entities without disabling routes are particularly valuable features.

This release is especially beneficial for:

• Projects with large collections that would benefit from the pagination: false option
• Applications that need more control over the admin UI navigation
• Projects using rich text fields within joins that have experienced truncation issues
• Anyone who has encountered the "blinking" effect with conditional fields in arrays or blocks

Since there are no breaking changes, the upgrade process should be smooth and straightforward.

Bug Fixes

Username Validation

Username validation has been updated to allow all special characters. Previously, only . and - special characters were allowed in usernames.

Rich Text Truncation in Joins

Fixed an issue where rich text fields were not properly truncated when displayed within a joins field. The fields now have proper CSS styling to truncate extended rich text elements inside a joins table.

Form State Rendering for Conditional Fields

Fixed an issue where conditional fields would "blink" in and out when rendered within an array or block row. The fix adds an isLoading: true prop and displays a loader within the row until form state returns with properly evaluated conditions.

PostgreSQL Database Upsert

Fixed an issue where payload.db.upsert with Drizzle adapters was inserting new rows instead of updating existing ones due to incorrect handling of the where parameter.

Read Access Control for Join Collections

Fixed an issue with join collection read access control in both GraphQL and admin UI to properly respect access control through the join field collections.

ReadOnly Props for Auth Fields

Fixed an issue where the readOnly prop was not being passed down to email and username auth fields, resulting in these fields not being properly disabled when update access was restricted.

Nested Docs Plugin Publishing

Fixed an issue in the nested-docs plugin where publishing a parent document would incorrectly publish child documents. The fix ensures that draft children documents don't get overwritten when the parent document is published.

New Features

Hide Entities Without Disabling Routes

You can now hide collections or globals from the navigation sidebar and dashboard without disabling their routes by setting admin.group: false. Previously, the admin.hidden property would both hide the entity and disable its routes.

admin: {
  group: false, // Hides from sidebar/dashboard but keeps routes accessible
},

Pagination-Free Queries

The new pagination: false option for REST and GraphQL queries improves performance on large collections by avoiding count queries:

// REST example
const results = await fetch('/api/your-collection?pagination=false');

// GraphQL example
const query = `
  query {
    YourCollection(pagination: false) {
      docs {
        id
        title
      }
    }
  }
`;

Predefined Migrations from Exports

Plugins can now export their own predefined migrations that can be created with:

pnpm payload migrate:create --file @payloadcms/plugin-someplugin/someMigration

Plugins need to export the migration in their package.json:

"exports": {
  "./someMigration": {
    "import": "./someMigration.mjs",
    "types": "./someMigration.mjs",
    "default": "./someMigration.mjs"
  }
}

Customizable Code Editor Height

You can now customize the minimum height of code editors:

{
  type: 'code',
  name: 'myCode',
  admin: {
    minHeight: 300 // Set custom minimum height in pixels
  }
}

waitUntil Property for Jobs

Added waitUntil property to payload.jobs.queue for better control over job execution timing.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Pagination-Free Queries

The new pagination: false option for REST and GraphQL queries significantly improves performance on large collections by avoiding count queries. This is particularly beneficial for collections with thousands of documents where pagination information isn't needed.

Form State Optimization

The fix for conditional fields not only improves the user experience by eliminating the "blinking" effect but also optimizes form state handling by setting fields into local form state with an isLoading prop, reducing unnecessary re-renders.

Impact Summary

Payload CMS v3.7.0 delivers several important improvements that enhance both developer and content editor experiences. The ability to hide entities from navigation without disabling routes provides more flexibility in designing admin interfaces. Performance improvements for large collections through the pagination: false option will be particularly valuable for data-heavy applications.

Bug fixes address several pain points including rich text truncation in joins fields, form rendering for conditional fields, and username validation. The fix for the PostgreSQL database upsert function ensures data integrity when updating records.

UI improvements and refactoring continue Payload's evolution toward modern React patterns, including migration away from React.forwardRef in preparation for React 19 compatibility.

For plugin developers, the ability to load predefined migrations from proper exports opens up new possibilities for creating more sophisticated plugins with their own migration paths.

Overall, this release represents a solid incremental improvement to Payload with no breaking changes, making it a recommended upgrade for all users.

Full Release Notes