TL;DR
Payload CMS v1.2.0: Customizable Headers and Internationalization
This release introduces two major features: customizable header labels for arrays and collapsibles, and internationalization (i18n) support for the admin panel. It also includes important breaking changes to how labels are used for code-based naming in GraphQL and TypeScript interfaces. Developers will need to update their configurations to maintain compatibility with existing code.
Migration Guide
for v1.2.0
Breaking Changes for Labels
If you previously used labels for collections, globals, or block names, you need to update your configuration to prevent breaking changes to your GraphQL API and TypeScript types:
For Collections:
// Before
{
slug: 'my-collection',
label: 'My Collection', // Used for GraphQL and TypeScript naming
// ...
}
// After
{
slug: 'my-collection',
label: 'My Collection', // Now only used for UI display
graphQL: {
singularName: 'MyCollection', // For GraphQL schema singular name
pluralName: 'MyCollections' // For GraphQL schema plural name
},
typescript: {
interface: 'MyCollection' // For TypeScript interface generation
}
// ...
}
For Globals:
// Before
{
slug: 'my-global',
label: 'My Global', // Used for GraphQL and TypeScript naming
// ...
}
// After
{
slug: 'my-global',
label: 'My Global', // Now only used for UI display
graphQL: {
name: 'MyGlobal' // For GraphQL schema name
},
typescript: {
interface: 'MyGlobal' // For TypeScript interface generation
}
// ...
}
For Blocks (within Block fields):
// Before
{
slug: 'my-block',
label: 'My Block', // Used for GraphQL naming
// ...
}
// After
{
slug: 'my-block',
label: 'My Block', // Now only used for UI display
graphQL: {
singularName: 'MyBlock' // For GraphQL schema name
}
// ...
}
Updating RowLabel to RowHeader
If you were using custom RowLabel components or functions:
// Before
{
fields: [
{
name: 'items',
type: 'array',
admin: {
components: {
RowLabel: MyCustomRowLabel
}
}
}
]
}
// After
{
fields: [
{
name: 'items',
type: 'array',
admin: {
components: {
RowHeader: MyCustomRowHeader
}
}
}
]
}
Upgrade Recommendations
Priority: High
This release contains breaking changes that require configuration updates if you're using labels for code-based naming. We recommend the following upgrade approach:
-
Audit Your Code: Identify all places where you rely on GraphQL schema names or TypeScript interfaces generated from labels.
-
Update Configurations: Add the appropriate graphQL and typescript properties to your collections, globals, and blocks as outlined in the migration guide.
-
Test Thoroughly: After upgrading, test your GraphQL queries and TypeScript code to ensure everything works as expected.
-
Explore New Features: Once your application is stable, consider implementing the new customizable headers and i18n support to enhance your admin panel.
For projects with extensive use of labels for code generation, consider allocating dedicated time for this upgrade to ensure all configurations are properly updated.
Impact Summary
Payload CMS v1.2.0 introduces significant improvements to the admin UI customization capabilities and internationalization support, but comes with important breaking changes to how labels are used for code generation.
The introduction of customizable header labels for arrays and collapsibles provides developers with much greater flexibility in creating intuitive editing experiences. This feature allows for dynamic headers that can display contextual information based on the content being edited, making complex data structures more manageable for content editors.
The addition of internationalization (i18n) to the admin panel is a major step forward for teams working across multiple languages, making Payload more accessible to non-English speaking users.
However, the breaking changes to how labels are used for code-based naming require careful attention during upgrade. Previously, labels were used to generate GraphQL schema names and TypeScript interfaces, but now these must be explicitly defined using dedicated properties. This change provides more control over code generation but requires configuration updates to maintain compatibility with existing code.
Overall, this release significantly enhances Payload's flexibility and international appeal while requiring some migration effort for existing projects.
