Payload CMS Release: 3.0.0-beta.31

TL;DR

PayloadCMS 3.0.0-beta.31 introduces significant improvements to internationalization with typed i18n support, enhances the admin UI with better icon handling, and fixes several critical bugs. This release includes breaking changes to the i18n system, admin icons configuration, and certain component props, requiring careful migration for existing projects.

Highlight of the Release

• Strongly typed i18n system for better developer experience and type safety
• Improved admin UI with updated icon handling replacing the previous favicon system
• Fixed collection labels display when using multiple locales
• Enhanced GraphQL schema generation
• Git repository initialization for new projects created with CPA
• PostgreSQL database connection improvements

Migration Guide

Migrating to Typed i18n

If you have custom translations, you'll need to update your code to work with the new typed i18n system:

1. For client-side translations:

const customTranslations = {
  en: {
    namespace: {
      key: 'Value',
    },
  },
}

type CustomTranslationKeys = NestedKeysStripped<typeof customTranslations.en>

type MyI18n = I18nClient<typeof customTranslations.en, CustomTranslationKeys>

const myI18n: MyI18n

myI18n.t('namespace:key') // Custom translations are now type-checked

2. For component-level translations:

const customTranslations = {
  en: {
    namespace: {
      key: 'Value',
    },
  },
}

type CustomTranslationKeys = NestedKeysStripped<typeof customTranslations.en>

export const MyComponent: React.FC = () => {
  const { i18n, t } = useTranslation<typeof customTranslations.en, CustomTranslationKeys>()

  return t('namespace:key')
}

Migrating from admin.favicon to admin.icons

Replace your existing favicon configuration:

// Old approach
const config = {
  admin: {
    favicon: '/path/to/favicon.ico',
  },
}

With the new icons configuration:

// New approach
const config = {
  admin: {
    icons: '/path/to/favicon.ico', // Simple string path
    // OR
    icons: {
      icon: '/path/to/icon.png',
      apple: '/path/to/apple-icon.png',
      // other icon types as needed
    },
    // OR
    icons: [
      { rel: 'icon', url: '/path/to/icon.png' },
      { rel: 'apple-touch-icon', url: '/path/to/apple-icon.png' },
    ],
  },
}

Updating Component Props

If you're using any of these components, update them to accept payload instead of config:

• RenderCustomComponent
• Logo
• DefaultTemplate
• DefaultNav

// Old approach
const MyComponent = ({ config }) => {
  // Component code
}

// New approach
const MyComponent = ({ payload }) => {
  // Component code
}

Upgrade Recommendations

This beta release contains several breaking changes that require code modifications. We recommend the following approach:

1. Review your custom translations: If you have custom translations, you'll need to update them to work with the new typed i18n system.

2. Update admin icon configuration: Replace any usage of admin.favicon with the new admin.icons property.

3. Check custom components: If you're using RenderCustomComponent, Logo, DefaultTemplate, or DefaultNav, update them to accept payload instead of config.

4. Test thoroughly: After upgrading, thoroughly test your application, especially if you're using custom translations, custom components, or have specific favicon configurations.

5. Update dependencies: Ensure all your PayloadCMS-related dependencies are updated to compatible versions.

Since this is a beta release, consider testing in a non-production environment first before deploying to production.

Bug Fixes

UI and Navigation Fixes

• Fixed step-nav breadcrumbs ellipsis display issues
• Resolved collection labels display problems when using multiple locales
• Fixed depth field errors in API view when no value is present
• Properly added readOnly styles to disabled radio fields
• Removed letter spacing in loading overlay for script languages, improving readability

Technical Fixes

• Implemented proper GraphQL schema generation
• Fixed named tab being incorrectly required in generated types when no required fields exist
• Resolved loader alias issues in Payload
• Fixed PostgreSQL database connection issues including "too many clients already" errors
• Corrected handling of React Server Components (RSCs) in custom components
• Fixed wrong translation key being used for upload sizes ('upload:Sizes' instead of 'upload:sizes')

New Features

Typed i18n System

PayloadCMS now provides a strongly typed internationalization system, offering better developer experience and type safety. This feature requires developers to update their custom translations to work with the new typing system.

Admin Icons Enhancement

The admin.favicon configuration has been replaced with a more flexible admin.icons property that aligns with Next.js metadata standards. This allows for more comprehensive icon configuration across different platforms and devices.

PNG Favicons Export

The UI now exports PNG favicons instead of SVG, improving compatibility across browsers and platforms.

Git Repository Initialization

The Create Payload App (CPA) now automatically initializes a git repository when creating new projects, streamlining the development workflow.

Expanded Translations

Added translations for the API view, React select components, and checkbox fields in collection views, enhancing the experience for international users.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Database Connection Improvements

The release includes fixes for PostgreSQL database connection issues, preventing "too many clients already" errors and undefined transaction problems, which should result in more stable performance for PostgreSQL users.

Better Component Handling

Improved handling of React Server Components (RSCs) in custom components, which should lead to better rendering performance and fewer errors in Next.js applications.

Impact Summary

PayloadCMS 3.0.0-beta.31 brings significant improvements to the developer experience with typed internationalization, better icon handling, and numerous bug fixes. The release introduces three breaking changes that require careful migration: the new typed i18n system, replacement of admin.favicon with admin.icons, and updated component props.

For developers, this means better type safety and a more robust development experience, but requires code updates to accommodate the breaking changes. Content editors will benefit from UI improvements, fixed collection labels with multiple locales, and expanded translations. International users will appreciate the enhanced translation coverage and better support for script languages.

The release also addresses several technical issues, including PostgreSQL database connection problems and GraphQL schema generation, resulting in a more stable and reliable CMS. Overall, this beta release represents a significant step forward in PayloadCMS's internationalization capabilities and admin UI experience, though it requires careful migration for existing projects.

Full Release Notes