Payload CMS Release: 3.0.0-beta.12

TL;DR

PayloadCMS v3.0.0-beta.12 introduces significant enhancements including a new email adapter system, JSON field schemas, Vue live preview support, and a collection count operation. This release also includes numerous bug fixes for PostgreSQL, MongoDB, and the Next.js admin panel. The most notable breaking change is the email system overhaul, requiring users to install the new @payloadcms/email-nodemailer package if they were using the built-in email functionality.

Highlight of the Release

• New email adapter system with dedicated @payloadcms/email-nodemailer package
• JSON field schemas for structured data validation
• Vue live preview package for Vue.js applications
• Collection count operation for efficient document counting
• Cloud storage adapters for various providers
• Improved PostgreSQL and MongoDB database fixes
• Enhanced client-side field validations in admin UI

Migration Guide

Email Adapter Migration

The most significant breaking change in this release is the email system overhaul. If you were using the built-in email functionality, you'll need to migrate to the new email adapter system:

1. Install the new package:

   npm install @payloadcms/email-nodemailer
   

2. Update your configuration:

   Before:

   // via payload.init
   payload.init({
     email: {
       transport: someNodemailerTransport,
       fromName: 'hello',
       fromAddress: '[email protected]',
     },
   })
   // or via email in payload.config.ts
   export default buildConfig({
     email: {
       transport: someNodemailerTransport,
       fromName: 'hello',
       fromAddress: '[email protected]',
     },
   })
   

   After:

   // Using new nodemailer adapter package
   import { nodemailerAdapter } from '@payloadcms/email-nodemailer'
   
   export default buildConfig({
     email: nodemailerAdapter({
       defaultFromAddress: '[email protected]',
       defaultFromName: 'hello',
       transport: someNodemailerTransport
     })
   })
   

3. Note that the ability to pass email configuration into the init function has been removed. All email configuration must be done in the config file.

4. If you were using the default ethereal.email functionality, you can still get similar behavior:

   export default buildConfig({
     email: nodemailerAdapter() // This will provide similar functionality to the old ethereal.email setup
   })
   

Node.js Version Requirement

This release upgrades the minimum required Node.js version from 18.17.0 to v18.20.2. Ensure your development and production environments meet this requirement.

Rich Text HTML Output Changes

If you're using the rich text Lexical editor and relying on specific HTML output classnames, be aware that this release includes breaking changes to the classnames of the converted HTML from the internal list HTML converter.

Upgrade Recommendations

This beta release contains significant improvements and bug fixes, making it worthwhile for developers who are already using Payload v3 beta versions. However, as this is still a beta release, it's recommended to:

1. Test thoroughly in a non-production environment before upgrading production systems.

2. Pay special attention to the email system changes if you're using email functionality. The migration to the new adapter system is straightforward but requires code changes.

3. Check your Node.js version to ensure it meets the new minimum requirement of v18.20.2.

4. Review your rich text HTML output if you're using custom styling that depends on specific classnames from the Lexical editor's HTML output.

5. Update any custom PostgreSQL queries that might be affected by the table name fixes.

For production systems, unless you specifically need the new features or fixes in this beta, it may be prudent to wait for the final v3.0.0 release. However, if you're already on the v3 beta track, upgrading to this version is recommended for the numerous bug fixes and improvements.

Bug Fixes

PostgreSQL Fixes

• Fixed validation issues with localized fields having the same name
• Corrected row table names that were not being built properly
• Fixed nested groups in nested blocks validation
• Resolved issues with version suffix table names
• Fixed relationship query pagination
• Corrected hasMany query operator

MongoDB Fixes

• Now ignoring end session errors that could cause application crashes
• Fixed failing contains query with special characters
• Corrected version fields indexSortableFields

Next.js Admin Panel Fixes

• Added client-side field validations to login and forgot-password views
• Fixed password and confirm password field types
• Added password matching validation when creating the first user
• Improved admin access control
• Fixed content-type header in getFile route
• Added CORS headers to API responses
• Removed requirement for handlers, improving filesystem handling

Rich Text Editor Fixes

• Fixed upload nodes visibility issues
• Ensured links work correctly
• Added error handling during HTML generation
• Fixed rendering of upload extra fields drawer

Other Fixes

• Ensured body limit is respected in API requests
• Fixed empty cell data handling in JSON fields
• Improved file persistence through form state changes
• Fixed issues with importing modules on Windows with file:// paths
• Corrected update many operation with drafts
• Fixed resaving media when using cloud storage plugin

New Features

Email Adapter System

PayloadCMS now uses a modular email adapter system, allowing for more flexibility in email delivery. The built-in nodemailer functionality has been moved to a dedicated @payloadcms/email-nodemailer package. This change enables easier integration with different email service providers.

JSON Field Schemas

A new JSON field schema feature has been added, allowing developers to define structured data validation for JSON fields. This provides better data integrity and validation for complex JSON data structures.

Vue Live Preview

The new @payloadcms/live-preview-vue package brings live preview functionality to Vue.js applications, expanding PayloadCMS's frontend framework support beyond React.

Collection Count Operation

A dedicated count operation has been added to collections, providing a more efficient way to count documents without retrieving the actual data. This is particularly useful for pagination and statistics.

Cloud Storage Adapters

New cloud storage adapters have been implemented, including support for Vercel Blob Storage. These adapters make it easier to store and manage media files in cloud environments.

Ukrainian Translations

Ukrainian language support has been improved with updated translations and proper date-fns key configuration.

Security Updates

No specific security fixes were mentioned in the release notes. However, the improvements to field validations in login and forgot-password views, as well as the password matching validation when creating the first user, contribute to better security practices in the admin interface.

Performance Improvements

Database Performance

Several database-related fixes in this release contribute to improved performance:

• Better handling of relationship queries in PostgreSQL, which should result in more efficient database operations
• Improved MongoDB query handling, particularly for contains queries with special characters
• More efficient version field indexing for better query performance

API Performance

• The new collection count operation provides a more efficient way to count documents without retrieving the actual data
• Improved body limit handling ensures better resource utilization for API requests
• Better CORS handling for API responses reduces unnecessary processing

Build and Development Performance

• Improved module importing on Windows platforms
• Enhanced type generation for better development experience
• De-flaked test suites for more reliable development workflows

Impact Summary

PayloadCMS v3.0.0-beta.12 represents a significant step forward in the v3 development track, with a focus on improving extensibility, reliability, and developer experience. The introduction of the email adapter system is particularly impactful, as it decouples email functionality from the core, allowing for more flexible integrations with various email service providers.

The addition of JSON field schemas enhances data validation capabilities, while the new Vue live preview package expands frontend framework support. The collection count operation provides a more efficient way to handle document counting, which is particularly valuable for large datasets.

Database improvements for both PostgreSQL and MongoDB address several pain points that users have encountered in previous beta versions, making the overall experience more stable. The cloud storage adapters, particularly for Vercel Blob Storage, align well with modern serverless deployment patterns.

For developers already using v3 beta versions, this release offers substantial improvements that justify upgrading, despite the breaking changes to the email system. The migration path is clear and well-documented, making the transition relatively straightforward.

Overall, this beta release demonstrates PayloadCMS's commitment to building a robust, flexible, and developer-friendly headless CMS that can adapt to various use cases and deployment scenarios.

Full Release Notes

// via payload.init
payload.init({
  email: {
    transport: someNodemailerTransport
    fromName: 'hello',
    fromAddress: '[email protected]',
  },
})
// or via email in payload.config.ts
export default buildConfig({
  email: {
    transport: someNodemailerTransport
    fromName: 'hello',
    fromAddress: '[email protected]',
  },
})

// Using new nodemailer adapter package

import { nodemailerAdapter } from '@payloadcms/email-nodemailer'

export default buildConfig({
  email: nodemailerAdapter() // This will be the old ethereal.email functionality
})

// or pass in transport

export default buildConfig({
  email: nodemailerAdapter({
    defaultFromAddress: '[email protected]',
    defaultFromName: 'Payload',
    transport: await nodemailer.createTransport({
      host: process.env.SMTP_HOST,
      port: 587,
      auth: {
        user: process.env.SMTP_USER,
        pass: process.env.SMTP_PASS,
      },
    })
  })
})

// Create custom email adapter

// myAdapter.ts
import type { EmailAdapter, SendMailOptions } from 'payload/types'

export const myAdapter: EmailAdapter = ({ payload }) => ({
  defaultFromAddress: defaults.defaultFromAddress,
  defaultFromName: defaults.defaultFromName,
  sendEmail: async (message) => {
    // Perform any logic here
    console.log(`To: '${message.to}', Subject: '${message.subject}'`)
    return Promise.resolve()
  },
})

// payload.config.ts
export default buildConfig({
  email: myAdapter()
})