Payload CMS Release: Release 1.6.4

TL;DR

Payload CMS v1.6.4 introduces support for large file uploads and fixes localization issues

This release significantly improves file upload capabilities by adding support for the express-fileupload middleware's useTempFiles and tempFileDir options, allowing for more efficient handling of large file uploads. It also fixes a bug where localized values were being hoisted even when localization was disabled. This update is particularly valuable for developers working with media-heavy Payload CMS implementations.

Highlight of the Release

• Support for express-fileupload middleware's useTempFiles and tempFileDir options
• Improved handling of large file uploads through temporary file processing
• Fixed bug where localized values were being hoisted even when localization was disabled
• Improved version configuration validation before handling version deletion

Migration Guide

No migration is required for this release. The new file upload features are opt-in through configuration options.

If you want to take advantage of the improved large file upload support:

1. Update your Payload configuration to use the new options:

export default buildConfig({
  // ... other config
  upload: {
    useTempFiles: true,
    tempFileDir: '/path/to/temp/directory', // Optional, defaults to os.tmpdir()
  }
})

Note that if you were relying on the previous behavior where localized values were being hoisted even when localization was disabled, you may need to update your code to account for the fixed behavior.

Upgrade Recommendations

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

• Work with large file uploads
• Experience memory issues during file uploads
• Use localization features

The upgrade should be straightforward with no breaking changes. Simply update your package with:

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

If you're experiencing memory issues with large file uploads, consider enabling the new useTempFiles option in your configuration after upgrading.

Bug Fixes

• Localization Value Hoisting: Fixed an issue where localized values were being hoisted even when localization was disabled. This ensures that the system only processes localization when it's explicitly enabled.
• Version Configuration Validation: Improved validation of version configurations before attempting to delete versions, preventing potential errors during version management operations.
• Aspect Ratio Handling: Fixed issues with aspect ratio handling in image processing.

New Features

Enhanced File Upload Capabilities

The primary feature in this release is the improved support for large file uploads:

• Support for express-fileupload Options: Added support for the useTempFiles and tempFileDir options from the express-fileupload middleware.
• Temporary File Processing: Reworked the upload system to accommodate the useTempFiles option, allowing large files to be stored temporarily on disk rather than in memory.
• Automatic Cleanup: Implemented direct clearing of temporary files in operations rather than using an injected hook, ensuring better resource management.
• Improved Image Processing: Enhanced handling of temporary file resizing buffers for more efficient image manipulation.

These improvements allow Payload to handle much larger file uploads without running into memory limitations, which is particularly useful for media-heavy applications.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

• Memory Usage Optimization: By supporting the useTempFiles option, this release significantly reduces memory usage when handling large file uploads. Instead of loading entire files into memory, they can now be processed from temporary files on disk.
• More Efficient File Processing: The reworked upload system provides more efficient handling of large files, reducing the risk of out-of-memory errors and improving overall system stability during upload operations.

Impact Summary

This release primarily impacts file upload functionality in Payload CMS, making it more robust and efficient for handling large files. The addition of support for useTempFiles and tempFileDir options from express-fileupload allows developers to process large files without loading them entirely into memory, which can prevent out-of-memory errors on servers with limited resources.

The fix for localization value hoisting ensures that the system behaves correctly when localization is disabled, which improves the predictability of the CMS behavior.

Overall, this release enhances Payload's capabilities for media-heavy applications while maintaining backward compatibility. The changes are particularly beneficial for sites that handle large media files like high-resolution images, videos, or documents.

Full Release Notes