Payload CMS Release: 3.0.0-beta.97

TL;DR

PayloadCMS v3.0.0-beta.97 introduces significant improvements to the developer experience with a new logger configuration system, updated template structures, and important UI fixes. This release enhances upload field functionality, fixes migration command exit codes, and improves validation feedback in the nested-docs-plugin. Performance optimizations for ESLint and test suites have also been implemented, making development workflows more efficient.

Highlight of the Release

• New logger configuration system directly in Payload config
• Fixed migration command exit codes for better CI/CD integration
• Improved upload field functionality with PostgreSQL and admin descriptions
• Updated website template directory structure
• Significant ESLint and test suite performance improvements

Migration Guide

Logger Configuration Changes

If you were previously trying to use loggerOptions or loggerDestination in initOptions, you'll need to migrate to the new logger property in the Payload config:

// Before (non-functional)
const payload = await initPayload({
  loggerOptions: { level: 'info' },
  loggerDestination: process.stdout,
  // other options...
});

// After
const payload = await initPayload({
  // other options...
});

// In your Payload config:
export default buildConfig({
  // ...
  logger: {
    options: { level: 'info' },
    destination: process.stdout,
  },
  // ...
});

Website Template Structure

If you're using the website template, be aware that the source directory structure has changed. For new projects, this won't require any migration, but if you're updating an existing project based on the template, you may need to adjust your file organization to match the new structure.

Upgrade Recommendations

This beta release includes important bug fixes and performance improvements that enhance the development and content editing experience. If you're already using Payload v3.0.0-beta.96, upgrading to beta.97 is recommended, especially if you:

1. Need better logger configuration options
2. Are experiencing issues with upload fields, particularly with PostgreSQL
3. Want to benefit from the improved ESLint performance
4. Have encountered problems with migration exit codes in CI/CD pipelines

As this is still a beta release, it's advisable to test thoroughly in a non-production environment before deploying to production.

Bug Fixes

UI Fixes

• Upload Field Description: Fixed an issue where the admin.description was not being displayed for upload fields.
• Upload with Has Many Bulk Select: Resolved a problem where bulk selection for uploads was not working correctly with PostgreSQL databases.
• Sort Change Events: Fixed propagation of sort change events through the list query provider, ensuring that sorting works correctly in the admin UI.
• Nested Docs Plugin Validation: The nested-docs-plugin now properly throws errors to the UI when children are not passing validation, providing clearer feedback to users.

System Fixes

• Migration Exit Codes: Fixed an issue where migration commands were not returning proper error codes on failure, which caused problems particularly in CI environments. This resolves issue #7031 for Payload 3.0.

New Features

Logger Configuration in Payload Config

The logger configuration has been moved from initOptions to the main Payload config, providing more flexibility and control. The previous loggerOptions and loggerDestination in initOptions (which were not functional) have been removed in favor of a new logger property in the Payload config.

You can now configure the logger in several ways:

// Logger options only
logger: {
   level: 'info',
}

// Logger options with destination stream
logger: {
   options: {
     level: 'info',
   },
   destination: process.stdout
},

// Logger instance
logger: pino({ name: 'my-logger' })

Updated Website Template Structure

The website template has been updated with an improved source directory structure, making it easier to organize and maintain your Payload-powered websites. This change provides a more intuitive file organization for new projects.

Exit Preview Mode Button

A new button has been added to exit preview mode in templates, improving the content editing experience by making it easier to switch between preview and edit modes.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

ESLint Performance Improvements

Significant improvements have been made to ESLint performance, particularly in the test suite:

• Test admin linting time reduced from over 3 minutes to just 8 seconds
• UI linting time remains consistent at 18 seconds
• Upgraded to typescript-eslint v8 and updated all ESLint packages

These improvements make the development workflow much more efficient, especially when running linting as part of CI/CD pipelines or pre-commit hooks.

Other Optimizations

• Removed duplicative loop over column state to determine linked cells
• Hoisted selection provider for better performance

Impact Summary

This release focuses on developer experience improvements and bug fixes that enhance both the development workflow and content editing experience. The new logger configuration system provides more flexibility for controlling log output, while the fixed migration exit codes improve CI/CD reliability. Content editors will benefit from several UI fixes, particularly around upload fields and validation feedback.

The ESLint performance improvements are particularly notable, with test suite linting time reduced from over 3 minutes to just 8 seconds, which will significantly improve development efficiency. The updated website template structure also provides a better starting point for new projects.

While this release doesn't introduce major new features, it represents an important step in stabilizing and refining Payload CMS as it approaches its 3.0 stable release. The changes are mostly non-breaking and focused on quality-of-life improvements for developers and content editors.

Full Release Notes