TL;DR

Payload CMS v0.15.0 introduces a powerful new versioning system with drafts and autosave functionality. This major update allows content creators to work with draft content, compare versions, and restore previous versions. The release also includes significant improvements to the rich text editor with indentation controls and enhanced upload capabilities, better relationship field performance, and numerous bug fixes for a more stable experience.

Highlight of the Release

• New versioning system with drafts and autosave functionality
• Enhanced rich text editor with indentation controls and improved upload handling
• Better relationship field performance and pagination
• Improved access control with more granular options for versions and drafts
• Numerous bug fixes and stability improvements

Migration Guide

Upgrading to v0.15.0

Versioning System Configuration

If you want to use the new versioning system, you'll need to add configuration to your collections and globals:

// For collections
{
  slug: 'posts',
  // ... other collection config
  versions: {
    drafts: true, // Enable drafts
    autosave: true // Enable autosave (requires drafts: true)
  }
}

// For globals
{
  slug: 'header',
  // ... other global config
  versions: {
    drafts: true, // Enable drafts
    autosave: true // Enable autosave (requires drafts: true)
  }
}

Rich Text Editor Indentation

The rich text editor now supports indentation. No configuration changes are needed to use this feature.

Custom Fields for Rich Text Uploads

To add custom fields to uploads in rich text editor:

{
  name: 'content',
  type: 'richText',
  admin: {
    upload: {
      collections: {
        'media': {
          fields: [
            {
              name: 'caption',
              type: 'text',
              label: 'Caption'
            }
          ]
        }
      }
    }
  }
}

Using the Versions API

To work with versions through the Local API:

// Get versions for a document
const versions = await payload.findVersions({
  collection: 'posts',
  id: '123'
});

// Get a specific version
const version = await payload.findVersionByID({
  collection: 'posts',
  id: '123',
  versionID: '456'
});

// Restore a version
await payload.restoreVersion({
  collection: 'posts',
  id: '123',
  versionID: '456'
});

Note on Dependencies

This version requires Node.js v14+ and may require using the --legacy-peer-deps flag when installing due to dependency updates.

Upgrade Recommendations

Recommended for: All users of Payload CMS, especially those who need content versioning, drafts, or autosave functionality.

Priority: Medium to High

This is a significant feature release that introduces powerful content management capabilities without breaking existing functionality. The versioning system alone makes this upgrade worthwhile for most content-focused applications.

Upgrade Steps:

1. Update your Payload dependency to v0.15.0:

   npm install [email protected] --legacy-peer-deps
   

   Note: The --legacy-peer-deps flag may be necessary due to dependency updates.

2. If you have custom field types or plugins, test them thoroughly with this new version.

3. Review your access control policies, especially if you plan to implement the versioning system, as there are new permissions to consider.

4. Update your TypeScript types if you're using TypeScript, as there are several new types related to versions.

5. Consider implementing the versioning system for your collections and globals where appropriate.

No database migrations are required for this update, but enabling versions will create new collections in your database to store version data.

Bug Fixes

UI and Interaction Fixes

• Fixed mobile styling on not found page
• Prevented loading edit views until data initializes
• Fixed inability to clear localized property values
• Improved relationship field option loading
• Fixed issues with searching in relationship fields
• Prevented "None" from appearing in hasMany relationship select options

Data Handling Fixes

• Fixed bug in how find merges drafts
• Ensured empty hasMany relationships save as empty arrays
• Fixed saving of cleared number values
• Ensured revisions retain all locales
• Fixed multipart/form-data handling to retain non-string values
• Fixed bug with version count accuracy

Rich Text Fixes

• Fixed key generation for RichText based on initialValue
• Fixed rare crash with link RTE element
• Ensured nested lists always render properly

Access Control and Security

• Fixed GraphQL upload access control
• Ensured overrideAccess is false if undefined while populating
• Fixed JWT to work without CSRF in config
• Fixed empty and sparse CSRF configuration handling

New Features

Versioning System

• Complete versioning system for both collections and globals
• Draft content support with ability to work on unpublished changes
• Autosave functionality to prevent content loss
• Version comparison with visual diffs between versions
• Ability to restore previous versions
• Version history with detailed information

Rich Text Editor Improvements

• Added indentation controls for better content formatting
• Enhanced upload handling with custom fields for uploaded media
• Improved link handling and void element insertion
• Better nested list rendering

API Enhancements

• GraphQL version collection resolvers
• Local API for versions on globals
• Path information added to GraphQL errors
• Pagination argument to optimize GraphQL relationships

Field Improvements

• Field hooks now receive sibling data
• Original document provided to field access control
• Empty string values now allowed in radio and select options
• Better relationship field performance with optimized querying

Security Updates

Access Control Improvements

• Fixed GraphQL upload access control to properly respect permissions
• Added ability for global access control to return query constraints
• Exposed original document to field access control for better security checks
• Improved access control for preventing reading of drafts

Authentication and Authorization

• Fixed JWT to work without CSRF in config for certain scenarios
• Improved CSRF configuration handling
• Better sanitization of server URL to prevent undefined in admin routes

Performance Improvements

Relationship Field Optimization

• Significantly improved relationship field performance with optimized querying
• Added pagination argument to optimize GraphQL relationships and local API usage
• Prevented loading duplicative relationship options

Rich Text Editor Performance

• Better handling of rich text elements for improved editor performance
• Optimized rendering of nested lists and indentation

Autosave Optimization

• Implemented debounce in autosave to reduce unnecessary saves
• Optimized version operations for better performance

Query Optimization

• Improved how find merges drafts for better query performance
• Optimized version comparison functionality
• Enhanced version history loading

Impact Summary

Payload CMS v0.15.0 represents a significant evolution in the platform's content management capabilities with the introduction of a comprehensive versioning system. This system includes drafts, autosave, version comparison, and restoration features that dramatically improve the content editing experience.

The versioning system allows content editors to work on drafts without affecting published content, automatically save their work to prevent data loss, compare different versions with visual diffs, and restore previous versions when needed. This brings Payload in line with enterprise CMS features while maintaining its developer-friendly approach.

Rich text editing has been substantially improved with indentation controls and enhanced upload handling, allowing for more sophisticated content formatting and media management. The ability to add custom fields to uploaded media within rich text provides greater flexibility for content teams.

For developers, the release offers significant performance improvements, particularly in relationship fields and GraphQL queries. The addition of pagination to relationship queries helps optimize data loading for large datasets. Access control has been enhanced with more granular options for versions and drafts, improving security while maintaining flexibility.

The numerous bug fixes address issues across the platform, from UI interactions to data handling, making this a stable and worthwhile upgrade for all Payload users.

Full Release Notes