Payload CMS Release: 3.28.1

TL;DR

Payload CMS v3.28.1 is a maintenance release focused on bug fixes and improvements. It addresses critical issues with image resizing, S3 storage socket cleanup, UI rendering problems, and type definitions. The release also includes improved Swedish translations, React context provider updates for React 19 compatibility, and fixes for form state rendering issues. This update is recommended for all users to ensure stable operation, especially those using image processing or S3 storage.

Highlight of the Release

• Fixed S3 storage socket cleanup to prevent memory leaks and resource exhaustion
• Corrected image height rounding when resizing with Sharp to prevent 'bad extract area' errors
• Resolved form state infinite render issues in the UI
• Improved Swedish translations for a more natural localization experience
• Updated React context providers to align with React 19 best practices

Migration Guide

No migration steps are required for this release. This is a patch release that fixes bugs and improves existing functionality without introducing breaking changes.

If you're experiencing S3 socket issues, you can now customize the request handler options:

requestHandler: {
  httpAgent: {
    maxSockets: 300,
    keepAlive: true,
  },
  httpsAgent: {
    maxSockets: 300,
    keepAlive: true,
  },
  // Optional timeouts for large file operations
  requestTimeout: 5_000,
  connectionTimeout: 5_000,
}

Upgrade Recommendations

This is a recommended upgrade for all Payload CMS users, especially those who:

1. Use S3 storage and have experienced socket-related issues
2. Process images with Sharp and have encountered dimension calculation errors
3. Have experienced UI rendering issues or form state problems
4. Use Swedish translations

The update is backward compatible and contains important bug fixes that improve stability and performance. Upgrade by running:

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

Bug Fixes

Image Processing

• Fixed incorrect height rounding when resizing images with Sharp, which previously caused "extract_area: bad extract area" errors in certain edge cases
• The fix ensures proper dimension calculations by disabling the fastShrinkOnLoad optimization when needed

Storage

• Fixed S3 storage socket cleanup issues by implementing proper request handler options
• Added default configuration for keepAlive and maxSockets to prevent socket leaks
• Added customizable options for requestHandler, requestTimeout, and connectionTimeout for advanced use cases

UI Improvements

• Fixed form state infinite render issues caused by unstable dependencies in the task queue
• Added RowLabelProvider context for blocks row labels to improve UI consistency
• Prevented fieldErrorsToast from showing empty errors list when no field errors are present
• Fixed incorrect types for field Label, Description, and Error server components

Localization

• Improved Swedish translations throughout the system
• Fixed awkward translations and incorrect terminology (e.g., "locale" was incorrectly referred to as "Lokal" instead of "Språk")
• Normalized loading toasts to use consistent formatting with dots to signify ongoing actions

New Features

No significant new features were introduced in this release. This is primarily a maintenance release focused on bug fixes and improvements to existing functionality.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

S3 Storage Performance

• Implemented proper socket management for S3 storage connections with configurable maxSockets and keepAlive settings
• Added ability to customize request timeouts for better handling of large file operations

UI Rendering

• Fixed form state infinite render loop that was causing unnecessary re-renders and potential performance degradation
• Stabilized the queueTask function within a useCallback to prevent excessive re-renders

Build Optimization

• Excluded plugin-cloud-storage, plugin-sentry, and plugin-stripe from bundling optimization to prevent issues with their /client exports
• This ensures proper functioning while maintaining optimal bundle sizes for other components

Impact Summary

Payload CMS v3.28.1 is a maintenance release that addresses several important bugs and improves system stability. The most significant fixes include resolving S3 storage socket cleanup issues that could cause memory leaks, correcting image resizing calculations that previously caused errors, and fixing UI rendering problems that affected form state.

For developers, the release provides more accurate type definitions for server components and aligns React context usage with React 19 best practices. Content editors will benefit from improved UI experiences with better error handling and block row labels. System administrators will appreciate the fixes to resource management, particularly in S3 storage connections.

The Swedish localization has been significantly improved, making the system more natural for Swedish-speaking users. Templates have been updated to use the latest versions of Payload and Next.js, ensuring compatibility across the ecosystem.

Overall, this release enhances stability and user experience without introducing breaking changes, making it a recommended upgrade for all Payload CMS users.

Full Release Notes