TL;DR
PayloadCMS v3.0.0-beta.57 brings significant enhancements to the developer experience with new features like username-based login, improved filtering capabilities for group and tab fields, and better TypeScript support. This release also includes important exports from the SEO plugin, fixes for translation fallbacks and UI alignment issues, and introduces breaking changes to API handlers and Lexical rich text editor. Developers should review the migration guide before upgrading, especially if they're using the Lexical API directly or the modified request handling functions.
Migration Guide
Breaking Changes Migration
API Handler Changes
If you're using PayloadRequestWithData or the related request handling functions, you'll need to update your code:
// Before
await addDataAndFileToRequest({ request: req })
addLocalesToRequestFromData({ request: req })
// After
await addDataAndFileToRequest(req)
addLocalesToRequestFromData(req)
Also note that PayloadRequestWithData has been removed in favor of PayloadRequest with optional types for data and locale.
Lexical Rich Text Editor Upgrade
If you're using the Lexical API directly, be aware that the upgrade from 0.16.0 to 0.16.1 may include undocumented breaking changes. Please review the Lexical changelog for details.
New Features Implementation
Username-based Login
To implement username-based login:
const config = buildConfig({
collections: [
{
slug: 'users',
auth: {
loginWithUsername: true,
// username field will be automatically injected
// email field will still be required but not unique
},
},
],
})
Using SEO Plugin Fields
To use the exported SEO plugin fields:
import {
MetaDescriptionField,
MetaImageField,
MetaTitleField,
OverviewField,
PreviewField
} from '@payloadcms/plugin-seo/fields'
const collection = {
slug: 'pages',
fields: [
// Other fields...
MetaTitleField({
hasGenerateFn: true,
}),
MetaDescriptionField({
hasGenerateFn: true,
}),
MetaImageField({
relationTo: 'media',
hasGenerateFn: true,
}),
]
}
Custom TypeScript Schema
To customize TypeScript type generation:
const config = buildConfig({
typescript: {
schema: (generatedSchema) => {
// Modify the generated schema
return {
...generatedSchema,
// Your customizations
}
}
}
})
Upgrade Recommendations
For Development Environments
We recommend upgrading to v3.0.0-beta.57 in development environments to test the new features and ensure compatibility with your codebase, especially if you're using:
- Custom API handlers with
PayloadRequestWithData
- Direct Lexical API integrations
- TypeScript with custom field types
For Production Environments
As this is still a beta release, exercise caution when upgrading production environments. If you need the specific features or bug fixes in this release, consider:
- Creating a staging environment to test the upgrade first
- Reviewing the breaking changes and ensuring your codebase is compatible
- Having a rollback plan in case of unexpected issues
Upgrade Steps
-
Update your package.json:
npm install @payloadcms/[email protected]
or
yarn add @payloadcms/[email protected]
-
If using the SEO plugin or Lexical rich text editor, update those packages as well:
npm install @payloadcms/plugin-seo@latest @payloadcms/richtext-lexical@latest
-
Review your codebase for any usage of the changed APIs mentioned in the migration guide
-
Run your test suite to ensure compatibility
Impact Summary
PayloadCMS v3.0.0-beta.57 delivers substantial improvements to developer experience and content management capabilities. The introduction of username-based authentication provides more flexibility in user management, while the ability to filter by fields within groups and tabs significantly enhances content discovery for editors.
For developers, the release offers better TypeScript support with customizable type generation and improved JSON field typing. The exported SEO plugin fields enable more modular and flexible implementation of SEO features across collections. The simplified API handler improves code clarity, though it introduces breaking changes that require attention during upgrade.
Content editors will benefit from UI improvements, including better modal alignment and enhanced filtering capabilities. International users gain Russian translations for the SEO plugin and improved translation fallback behavior.
The Lexical rich text editor upgrade brings the latest improvements but may introduce breaking changes for those using the Lexical API directly. Overall, this release balances new features with important bug fixes and performance improvements, making it a valuable update for most PayloadCMS users, though the breaking changes require careful consideration during the upgrade process.
