Payload CMS Release: 3.0.0-beta.112

TL;DR

Payload CMS v3.0.0-beta.112 introduces significant improvements to CSS architecture with a new layering system, enhances join fields to work with hasMany relationships, fixes several UI and authentication issues, and includes two breaking changes affecting auth provider usage and CSS specificity. This release focuses on improving developer experience with better styling control and fixing critical bugs in file handling, authentication flows, and UI components.

Highlight of the Release

• New CSS layering system with @layer payload-default for better styling control
• Join fields now work with hasMany relationships
• Improved authentication provider with better logout handling
• Fixed file handling with proper aspect ratio calculations and resize after cropping
• Added German translation to the SEO plugin

Migration Guide

Migrating to the New CSS Layer System

If you have custom CSS overriding Payload styles, you'll need to adapt to the new layering system:

1. Review your custom CSS that targets Payload components
2. For styles that need to maintain the same specificity as Payload's styles:

@layer payload-default {
  /* Place your existing overrides here */
}

3. For styles that should have higher specificity than Payload's:

/* Place styles outside of any layer for highest specificity */

4. For styles that should be applied after Payload's but still use the layering system:

@layer payload {
  /* Your styles here */
}

Updating setUser Function Usage

If you're using the setUser function from the useAuth() provider, update your implementation:

// Before
setUser({
  id: '670524817048be0fa222fc01',
  email: '[email protected]',
  // ... other user properties
})

// After
setUser({
  user: {
    id: '670524817048be0fa222fc01',
    email: '[email protected]',
    // ... other user properties
  },
  exp: 1728398351,
  token: "....eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC...."
})

The new format expects the response data structure from auth-enabled endpoints like the /me route, allowing proper synchronization of cookies and expiration when setting a new user.

Upgrade Recommendations

This release contains two breaking changes that affect CSS styling and authentication, so careful testing is recommended before upgrading production environments.

For Development Environments:

• Upgrade immediately to benefit from bug fixes and new features
• Test thoroughly any custom CSS implementations and authentication flows

For Production Environments:

• Plan for the CSS and authentication changes before upgrading
• Test in a staging environment first, particularly if you have:
  • Custom CSS overriding Payload styles
  • Custom authentication implementations using the setUser function
  • Complex file handling with resizing and cropping

The improvements to file handling, join fields with hasMany relationships, and UI components make this a valuable upgrade for most users, but the breaking changes require attention during the upgrade process.

Bug Fixes

Authentication and Authorization

• Fixed issue where verify view was accessible when it shouldn't be
• Improved redirect handling and context for authentication flows
• Added toast notification when redirecting to login route after verification

File Handling

• Fixed calculation of aspect ratio dimensions on Sharp-based files
• Now correctly applies resize after cropping when resizeOptions are defined
• Fixed duplicate operation with upload collections

UI Components

• Added unstyled={true} prop to React-Select elements so Payload styles take priority
• Fixed issue where React-Select's injected styles had higher specificity than Payload styles

Rich Text Editor

• Fixed issue where linkFeature didn't respect admin.routes from payload.config.ts

Templates

• Fixed proper awaiting of params/cookies in templates
• Removed duplicative join field test
• Deflaked Lexical e2e test by improving URL pattern matching
• Added pg dependency to db-vercel-postgres
• Hidden admin bar for website template on small screens

New Features

CSS Layering System

All Payload CSS is now encapsulated inside CSS layers under @layer payload-default. This provides better specificity control, allowing custom CSS to have the highest possible specificity. A new @layer payload is also available for ensuring custom styles are applied after Payload's styles. To override existing styles while respecting specificity rules, you can use:

@layer payload-default {
  /* custom styles within payload specificity */
}

Join Field with hasMany Relationships

Join fields now work properly with relationships and uploads that have hasMany: true enabled. This expands the flexibility of join fields, allowing them to be used in more complex data structures.

German Translation for SEO Plugin

Added German translation to the SEO Plugin, improving accessibility for German-speaking users.

Improved Authentication Provider

Enhanced the authentication provider with better logout handling:

• Uses overlay modal for "logging out..." display
• Direct navigation to login page after manual logout
• Explanatory logout page for inactivity-triggered logouts
• Fixed cookie refresh issues after user logout
• Cleaner auth provider timeouts for refresh and force logout

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

CSS Performance

The new CSS layering system not only improves developer experience but also helps with performance by better organizing styles and reducing specificity conflicts. This can lead to more efficient style resolution by browsers.

Authentication Flow

Improved authentication provider implementation with cleaner timeout handling for refresh and force logout, reducing unnecessary operations and potential memory leaks.

Test Stability

Several improvements to test stability, including:

• Deflaked Lexical e2e test with better URL pattern matching
• Removed duplicative join field tests that were causing errors when running tests locally

Impact Summary

This release significantly enhances Payload CMS with a new CSS architecture that provides better control over styling specificity through a layering system. It also expands the capabilities of join fields to work with hasMany relationships, improves authentication flows, and fixes several critical bugs in file handling and UI components.

The two breaking changes - the new CSS layering system and updated setUser function signature - require attention during upgrade, but provide better developer experience and more consistent behavior. The CSS changes give developers more control over styling specificity, while the authentication changes improve the synchronization between user state and cookies.

For content editors, the release brings UI improvements, better authentication experiences, and fixes for rich text editing. Developers will appreciate the expanded join field capabilities, improved file handling with proper aspect ratio calculations, and the ability to duplicate upload collections.

Overall, this release focuses on improving developer experience, fixing critical bugs, and enhancing the platform's flexibility while maintaining backward compatibility where possible.

Full Release Notes