Payload CMS Release: Release v2.6.0

TL;DR

Payload CMS 2.6.0: Enhanced Localization, MongoDB Transactions, and UI Improvements

This release introduces powerful localization features with locale-specific fallbacks, giving developers more control over multi-language content. MongoDB users gain transaction configuration options, and several GraphQL and UI fixes improve the overall developer experience. The update also enhances language detection from browser headers and fixes various issues with rich text editing, navigation, and field validations.

Highlight of the Release

• New locale-specific fallbacks for more granular control over multi-language content
• MongoDB transaction options for configuring database operations
• Improved GraphQL support for querying multiple locales
• Better language detection from browser headers
• Fixed UI issues with rich text editing, navigation, and field validations

Migration Guide

Migrating to Locale-Specific Fallbacks

If you're using localization in your Payload project, you can now take advantage of locale-specific fallbacks. This is a non-breaking change and your existing configuration will continue to work.

To migrate to the new locale-specific fallbacks:

1. Update your localization configuration from the flat format:

// Old format
export default buildConfig({
  localization: {
    locales: ['en', 'es', 'pt'],
    defaultLocale: 'en',
    fallback: true // Global fallback setting
  }
})

To the new object format with specific fallbacks:

// New format
export default buildConfig({
  localization: {
    locales: [
      {
        label: 'English',
        code: 'en',
        fallbackLocales: []
      },
      {
        label: 'Spanish',
        code: 'es',
        fallbackLocales: ['en']
      },
      {
        label: 'Portuguese',
        code: 'pt',
        fallbackLocales: ['es', 'en']
      }
    ],
    defaultLocale: 'en'
  }
})

MongoDB Transaction Options

If you're using MongoDB and want to configure transaction options, you can add them to your database configuration:

export default buildConfig({
  db: {
    mongo: {
      transactionOptions: {
        // Your MongoDB transaction options here
        readPreference: 'primary',
        readConcern: { level: 'local' },
        writeConcern: { w: 'majority' }
      }
    }
  }
})

Upgrade Recommendations

This release contains significant improvements to localization features and fixes several important bugs. We recommend all users upgrade to version 2.6.0, especially if you:

• Use multiple languages in your Payload project
• Work with MongoDB and need transaction configuration options
• Use GraphQL with multiple locales
• Have experienced any of the UI or field validation issues fixed in this release

The upgrade should be straightforward with no breaking changes reported. Update your Payload dependency to version 2.6.0:

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

After upgrading, test your application thoroughly, especially if you rely heavily on localization features or GraphQL queries with multiple locales.

Bug Fixes

GraphQL and API Improvements

• Fixed issues with GraphQL queries that use multiple locales
• Fixed a bug where req.locale and req.fallbackLocale were incorrectly reassigned in local operations
• Made locale and fallback locale handling more consistent for globals

UI and Navigation Fixes

• Fixed z-index issues in the Lexical rich text editor that caused overlay problems
• Fixed navigation lock when closing modals with the ESC key
• Fixed an issue where the actions array wasn't properly reset when navigating out of views with actions

Field and Validation Fixes

• Fixed JSON field Joi schema to properly allow editorOptions
• Fixed tab field errors that occurred when using the same interface name in different tabs
• Added support for RTL header locale selector

Database and System Fixes

• Fixed PostgreSQL transaction handling to properly wait for transactions to complete on commit
• Updated nodemailer to fix "The punycode module is deprecated" warning
• Fixed template building issues after type generation

New Features

Enhanced Localization with Locale-Specific Fallbacks

Payload now supports locale-specific fallbacks, allowing developers to define different fallback languages for each locale in their system. This provides more granular control over how content is displayed when translations are missing in a specific language.

export default buildConfig({
  localization: {
    locales: [
      {
        label: 'English',
        code: 'en',
        fallbackLocales: [] // No fallbacks for English
      },
      {
        label: 'Spanish',
        code: 'es',
        fallbackLocales: ['en'] // Falls back to English
      },
      {
        label: 'Portuguese',
        code: 'pt',
        fallbackLocales: ['es', 'en'] // Falls back to Spanish first, then English
      }
    ],
    defaultLocale: 'en'
  }
})

MongoDB Transaction Options

For MongoDB users, this release adds the ability to configure transaction options, providing more control over database operations:

export default buildConfig({
  db: {
    mongo: {
      transactionOptions: {
        readPreference: 'primary',
        readConcern: { level: 'local' },
        writeConcern: { w: 'majority' }
      }
    }
  }
})

Improved Language Detection

Payload now better detects user language preferences from browser request headers (accept-language), making the admin UI and API responses more likely to match the user's preferred language automatically.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Database Transaction Improvements

The PostgreSQL adapter now properly waits for transactions to complete on commit, which improves reliability and prevents potential race conditions in database operations.

E2E Test Improvements

Several improvements to end-to-end tests have been made, including better selectors for locale changes and proper awaiting of operations, which should lead to more reliable test runs and fewer false negatives.

Impact Summary

Payload CMS 2.6.0 brings significant improvements to localization capabilities with the introduction of locale-specific fallbacks, allowing for more granular control over content translation fallback behavior. This is particularly valuable for multilingual sites with complex language hierarchies.

The addition of MongoDB transaction options gives database administrators and developers more control over database operations, which can be crucial for applications with specific performance or consistency requirements.

Several important bug fixes address issues in the GraphQL API, UI navigation, and field validations. The fix for GraphQL multiple locales queries is especially important for applications that rely on fetching content in different languages via GraphQL.

The improved language detection from browser headers enhances the user experience by automatically selecting the appropriate language based on user preferences, making the CMS more accessible to international teams.

Overall, this release focuses on enhancing developer control, improving multilingual support, and fixing various UI and API issues that impact the day-to-day use of Payload CMS.

Full Release Notes