3.44.0

TL;DR

Payload CMS v3.44.0: Enhanced Security, Better UI, and Improved Database Support

This release introduces a significant security enhancement with auth sessions (enabled by default), requiring a migration for PostgreSQL and SQLite users. It also brings collection-level preferences, UI improvements for relationship fields and error handling, and fixes for database adapters including MongoDB, PostgreSQL, and Drizzle. The release includes better CSV export handling, live preview enhancements, and numerous bug fixes across the admin UI.

Important: PostgreSQL and SQLite users with local auth need to migrate their databases or opt out by setting auth.useSessions: false in their user collection config.

Highlight of the Release

• New auth sessions feature for improved security (enabled by default)
• Collection-level preferences and disableBulkEdit option
• Simplified job type handling with the new Job type
• Improved UI for relationship fields and error handling
• Better CSV export handling in the import-export plugin
• Fixed issues with live preview and relationship population

Migration Guide

Auth Sessions Migration

For PostgreSQL and SQLite Users:

If you're using the local auth strategy with db-postgres or db-sqlite, a migration is required due to the new auth sessions feature. This feature stores a unique session identifier in the database for each authenticated user.

Option 1: Migrate Your Database

You'll need to add a new column to your users table to store the session information. The exact migration will depend on your database schema and setup.

Option 2: Opt Out of Auth Sessions

If you prefer to continue using the previous behavior with stateless JWTs, you can disable the feature by setting auth.useSessions: false in your users collection config:

// payload.config.ts
collections: [
  {
    slug: 'users',
    auth: {
      useSessions: false,
    },
    fields: [],
  },
],

Job Type Changes

If you're using job types in your code, there are several deprecated types that should be replaced:

• GeneratedTypes['payload-jobs']
• BaseJob
• RunningJob<>

These should all be replaced with the new Job type, which:

• Works in both monorepo and installed projects
• Falls back to BaseJob if no generated types exist
• Includes an optional generic to narrow down job.input based on task/workflow slug

External Resource Handling

If you're experiencing issues with external resources being blocked, you can now use:

// payload.config.ts
export default buildConfig({
  upload: {
    // Allow specific external URLs to bypass safe fetch checks
    skipSafeFetch: ['trusted-domain.com', 'api.example.org'],
    
    // Allow specific external URLs for pasting
    pasteURL: {
      allowList: ['images.example.com', 'cdn.trusted-source.net']
    }
  }
})

Upgrade Recommendations

Priority Level: Medium

This release contains important security enhancements and numerous bug fixes, making it a recommended upgrade for most users.

Who should upgrade immediately:

• Users experiencing any of the specific bugs fixed in this release
• Those who want to take advantage of the new auth sessions security feature
• Projects using PostgreSQL with custom schemas or relationship fields
• Anyone using the import/export plugin with CSV exports

Upgrade Steps:

1. Update your Payload dependencies to v3.44.0

   npm install payload@3.44.0
   # or
   yarn upgrade payload@3.44.0
   # or
   pnpm update payload@3.44.0
   

2. If using PostgreSQL or SQLite with local auth, either:

   • Prepare a database migration for the new auth sessions feature
   • Opt out by setting auth.useSessions: false in your users collection config

3. If using job types in your code, replace deprecated types (GeneratedTypes['payload-jobs'], BaseJob, RunningJob<>) with the new Job type

4. Test your application thoroughly, especially if you're using features that received significant fixes (relationship fields, CSV exports, live preview)

Considerations:

• The auth sessions feature is a significant change to authentication behavior but provides better security
• Review the full changelog for any specific fixes that might affect your implementation

Bug Fixes

Database Fixes

• Fixed querying on hasMany: true select fields in relationships with PostgreSQL
• Fixed joins with custom schema in PostgreSQL
• Fixed an issue where deleted blocks from config would cause errors in MongoDB
• Fixed an issue where sorting on virtual fields would cause runtime errors in Drizzle

UI Improvements

• Fixed unreachable custom views when admin route is set to '/'
• Fixed bulk upload losing state when adding additional files
• Fixed date format of useAsTitle being lost after changing values
• Fixed custom row labels on arrays being removed on field duplication
• Fixed alignment of error tooltip carets for checkbox fields
• Fixed rendering of DateTime labels as proper <label> elements
• Fixed proper rendering of "Create new" buttons in polymorphic joins
• Fixed issues with auth fields UI not reflecting access control settings
• Fixed table header vertical alignment

Live Preview Fixes

• Fixed client-side live preview being unable to populate more than 10 relationships at once
• Fixed foreign postMessage events resetting client-side state
• Fixed missing properties in live preview client config
• Fixed live preview popup triggering "leave without saving" modal

Import/Export Plugin Fixes

• Fixed duplicated rows and headers in CSV export when streaming paginated results
• Fixed CSV export for polymorphic relationship fields
• Fixed omission of CSV columns when toCSV returns undefined

Other Fixes

• Fixed validation of "null" value for point fields when not required
• Fixed external resource blocking with new skipSafeFetch and allowList options
• Fixed issues with querying virtual fields deeply with draft: true
• Fixed Next.js auth functions error handling

New Features

Auth Sessions

A major security enhancement that stores unique auth session identifiers in the database, enabled by default for all authentication collections. This provides better security than the previous stateless JWT approach. Users can opt out by setting auth.useSessions: false in their collection config.

Collection-Level Preferences

Added support for collection-level preferences under a general key collection-<slug>, allowing for storage of preferences that aren't specific to the list view. This pattern matches existing conventions for document-level preferences.

Collection-Level disableBulkEdit

Added the ability to disable bulk editing operations at the collection level by setting admin.disableBulkEdit: true in the collection config.

Improved CSV and JSON Data Preview

The import-export plugin now displays CSV and JSON data more accurately in the preview, using the same logic as the CSV export. This ensures consistency between what you see in the preview and what gets exported.

Template Testing Improvements

Added integration and end-to-end tests to blank and website templates, making them more robust and easier to maintain.

Security Updates

Auth Sessions

This release introduces a significant security enhancement with the new auth sessions feature. Instead of relying solely on stateless JWTs, Payload now stores a unique session identifier in the database for each authenticated user. This provides better security and control over user sessions.

This feature is enabled by default for all authentication collections. If you're using PostgreSQL or SQLite, a database migration is required. You can opt out by setting auth.useSessions: false in your collection config.

External Resource Protection

Fixed issues with external resource blocking by adding:

• [Config].upload.skipSafeFetch to allow specific external URLs
• [Config].upload.pasteURL.allowList to allow specific external URLs for pasting

This helps prevent security issues related to fetching external resources while still allowing legitimate use cases.

Performance Improvements

Job Queue Improvements

The job queue error handling has been significantly simplified, resulting in better performance. Previously, task/workflow failure or cancellation would result in multiple, separate updateJob database calls as data modifications were done in multiple areas of the codebase. Now, there's a clean, single updateJob call with new TaskError, WorkflowError, and JobCancelledError error types that are thrown and handled in one place.

Package Size Reduction

Removed unused assets from the payload package, decreasing the install size (excluding dependencies) from 6.22MB to 5.12MB. This should result in faster installations and smaller bundle sizes.

Code Optimization

Changed default exports to named exports in the payload package and removed unnecessary internal-only barrel export files, resulting in less code and fewer ESLint warnings.

Impact Summary

Payload CMS v3.44.0 brings significant improvements across security, user interface, and database support. The most notable change is the introduction of auth sessions, a security enhancement enabled by default that requires database migrations for PostgreSQL and SQLite users (with an opt-out option available).

The release simplifies development with a new unified Job type, adds collection-level preferences and bulk edit controls, and improves the import/export plugin's CSV handling. UI enhancements fix numerous issues with relationship fields, error tooltips, and form handling.

Database adapter improvements address specific issues in MongoDB, PostgreSQL, and Drizzle, particularly around relationships, custom schemas, and virtual fields. The live preview functionality received several fixes for relationship population and state management.

Performance improvements come from simplified job queue error handling and reduced package size. The codebase has been refactored to use named exports instead of default exports, resulting in cleaner code and fewer ESLint warnings.

Overall, this is a substantial release that enhances security, fixes numerous bugs, and improves the developer and content editor experience. The auth sessions feature represents an important security improvement, though it requires attention from database administrators using PostgreSQL or SQLite.

Full Release Notes

// payload.config.ts
collections: [
  {
    slug: 'users',
    auth: {
      useSessions: false,
    },
    fields: [],
  },
],