TL;DR
PayloadCMS v3.0.0-beta.96 brings significant performance improvements by reducing the package size from 115MB to 34MB, fixes critical bugs in localization and validation, and introduces a breaking change in how nested localized fields are handled. This release focuses on optimizing the developer experience while ensuring better compatibility across database types.
Highlight of the Release
- Package size reduced from 115MB to 34MB by removing unnecessary dependencies
- Breaking change: Auto-removal of redundant localized properties in nested fields
- Fixed PostgreSQL bug with nested localized arrays
- Improved validation errors for unique fields
- Fixed UI issues with duplicate active nav indicators
Migration Guide
Migrating Nested Localized Fields
This release introduces a breaking change in how nested localized fields are handled. If you're using MongoDB and have configurations with localized fields nested within other localized fields, you'll need to take action:
-
Understand the change: Payload now automatically removes the localized: true property from fields nested within already localized parent fields, as this configuration is redundant and causes errors in PostgreSQL.
-
Option 1 - Recommended: Remove the redundant localized: true properties from your field configurations manually.
-
Option 2 - Compatibility mode: If you need to maintain existing behavior temporarily, add the following to your Payload config:
export default buildConfig({
// Your existing config
compatibility: {
allowLocalizedWithinLocalized: true
}
})
Only use this compatibility flag if you have an existing MongoDB database from pre-3.0 with nested localized fields that you want to maintain without migrating.
Upgrade Recommendations
Priority: Medium-High
-
MongoDB users: If you have configurations with nested localized fields, review them before upgrading. Consider testing the upgrade in a non-production environment first.
-
PostgreSQL users: This upgrade is highly recommended as it fixes critical issues with nested localized arrays.
-
All users: The significant reduction in package size (115MB → 34MB) makes this upgrade beneficial for all users from a performance perspective.
To upgrade:
npm install [email protected]
# or
yarn add [email protected]
# or
pnpm add [email protected]
After upgrading, test your application thoroughly, especially if you use localized fields within your schema.
Bug Fixes
Fixed PostgreSQL Nested Localized Arrays
Fixed a bug with nested arrays within localized blocks or arrays in PostgreSQL databases that was causing errors.
Improved Validation Errors for Unique Fields
Enhanced the validation error messages for unique fields to provide clearer feedback to users when uniqueness constraints are violated.
Fixed Duplicate Active Nav Indicators
Resolved an issue where navigation items could show duplicate active indicators in the admin UI.
Corrected Config.upload Types
Fixed incorrect type definitions for config.upload and now properly exporting FetchAPIFileUploadOptions from Payload, addressing issues with TypeScript type checking.
New Features
Auto-removal of Redundant Localized Properties
Payload now automatically removes the localized: true property from fields that are nested within already localized parent fields. This prevents redundant localization configurations that could cause errors, particularly in PostgreSQL and SQLite databases.
Significant Package Size Reduction
The total install size of Payload has been reduced from 115MB to 34MB by:
- Removing the unnecessary
monaco-editor dependency (only using the much smaller @monaco-editor/react)
- Upgrading
json-schema-to-typescript to reduce dependencies
These changes make Payload more lightweight and faster to install while maintaining all functionality.
Security Updates
No specific security fixes were mentioned in this release.
Performance Improvements
Dramatic Package Size Reduction
The total install size of Payload has been reduced by approximately 70%, from 115MB to 34MB. This was achieved by:
- Removing the unnecessary
monaco-editor dependency, which was never directly used within Payload (only @monaco-editor/react was needed)
- Upgrading
json-schema-to-typescript to reduce the number of dependencies
These changes significantly improve installation times, reduce disk space usage, and potentially improve load times for developers.
Dependency Optimization
The upgrade to json-schema-to-typescript not only reduces package size but also decreases the overall number of dependencies, leading to a more streamlined and maintainable codebase.
Impact Summary
This release significantly improves the developer experience by reducing the package size by 70% (from 115MB to 34MB) and fixing several important bugs. The most notable change is the breaking change in how nested localized fields are handled - Payload now automatically removes redundant localized: true properties from fields nested within already localized parent fields.
For MongoDB users, this could require configuration changes if you've been using nested localized fields. A compatibility flag (compatibility.allowLocalizedWithinLocalized) has been provided for those who need to maintain existing behavior.
PostgreSQL users will benefit from fixed bugs with nested localized arrays, which previously caused errors. All users will experience improved validation error messages for unique fields and UI fixes for navigation indicators.
The package size reduction was achieved by removing unnecessary dependencies like monaco-editor and upgrading json-schema-to-typescript, making Payload more lightweight and faster to install without sacrificing functionality.
Full Release Notes
🚀 Features
- auto-removes localized property from localized fields within other localized fields (#7933) (538b7ee)
- significantly reduce payload install size by removing unnecessary monaco-editor dependency (#7939) (e375f6e)
- reduce package size and amount of dependencies by upgrading json-schema-to-typescript (#7938) (dc12047)
🐛 Bug Fixes
⚠️ BREAKING CHANGES
-
auto-removes localized property from localized fields within other localized fields (#7933) (538b7ee)
Payload localization works on a field-by-field basis. As you can nest
fields within other fields, you could potentially nest a localized field
within a localized field—but this would be redundant and unnecessary.
There would be no reason to define a localized field within a localized
parent field, given that the entire data structure from the parent field
onward would be localized.
Up until this point, Payload would allow you to nest a localized field
within another localized field, and this might have worked in MongoDB
but it will throw errors in Postgres.
Now, Payload will automatically remove the localized: true property
from sub-fields within sanitizeFields if a parent field is localized.
This could potentially be a breaking change if you have a configuration
with MongoDB that nests localized fields within localized fields.
Migrating
You probably only need to migrate if you are using MongoDB, as there,
you may not have noticed any problems. But in Postgres or SQLite, this
would have caused issues so it's unlikely that you've made it too far
without experiencing issues due to a nested localized fields config.
In the event you would like to keep existing data in this fashion, we
have added a compatibility.allowLocalizedWithinLocalized flag to the
Payload config, which you can set to true, and Payload will then
disable this new sanitization step.
Set this compatibility flag to true only if you have an existing
Payload MongoDB database from pre-3.0, and you have nested localized
fields that you would like to maintain without migrating.
Contributors
