Payload CMS Release: 3.18.0

TL;DR

Payload CMS v3.18.0 introduces significant performance optimizations, reducing form state response size by up to 3x and improving overall response times. The release adds a new multi-tenant plugin for managing content across different tenants, enhances upload capabilities with server-side URL fetching, and improves field validation error messages. Several bug fixes address issues in rich text editors, form state handling, and UI components. TypeScript strictness has been improved across packages, and new examples for Remix and Astro integration have been added.

Highlight of the Release

• New multi-tenant plugin for managing content across different tenants
• Performance optimizations reducing form state response size by up to 3x
• Enhanced upload capabilities with server-side URL fetching
• Improved field validation error messages using field labels
• New examples for Remix and Astro integration with Payload Local API
• Support for JPEG XL image size calculation

Migration Guide

Multi-Tenant Plugin Configuration

If you're implementing the new multi-tenant plugin, you'll need to:

1. Add a tenants collection to your Payload config
2. Configure the plugin with your collections:

import type { Config } from './payload-types'
import { buildConfig } from 'payload'
import { multiTenantPlugin } from '@payloadcms/plugin-multi-tenant'

export default buildConfig({
  plugins: [
    multiTenantPlugin<Config>({
      collections: {
        pages: {},
        // For collections that should behave like globals
        navigation: {
          isGlobal: true,
        },
      },
      // Optional: function to determine if a user has access to all tenants
      userHasAccessToAllTenants: (user) => isSuperAdmin(user),
    }),
  ],
})

Server-Side URL Fetching Configuration

If you want to enable server-side URL fetching for uploads:

import type { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  upload: {
    pasteURL: {
      allowList: [
        {
          hostname: 'payloadcms.com', // required
          pathname: '',
          port: '',
          protocol: 'https', // defaults to https
          search: ''
        },
        {
          hostname: 'example.com',
          pathname: '/images/*',
        },
      ],
    },
  },
}

TypeScript Strictness

If you're extending Payload types or creating plugins, be aware that TypeScript strictness has been increased with:

• strict: true
• noUncheckedIndexedAccess: true
• noImplicitOverride: true

You may need to update your code to comply with these stricter settings.

Upgrade Recommendations

This release contains significant performance improvements and new features without breaking changes, making it a recommended upgrade for all Payload users.

Who should upgrade immediately:

• Users experiencing performance issues with form state or list views
• Developers implementing multi-tenancy solutions
• Users who need to upload files from external URLs that currently face CORS issues
• Projects that would benefit from the TypeScript strictness improvements

Upgrade Steps:

1. Update your Payload dependencies:

   npm install [email protected]
   # or
   yarn add [email protected]
   # or
   pnpm add [email protected]
   

2. If you're using any Payload plugins, update those as well to ensure compatibility.

3. Test your application thoroughly after upgrading, especially if you're using custom field hooks or have implemented custom form state handling.

4. If you want to take advantage of the new multi-tenant plugin, install it separately:

   npm install @payloadcms/plugin-multi-tenant
   

The upgrade should be straightforward for most users as there are no breaking changes reported in this release.

Bug Fixes

Rich Text Editor Fixes

• Fixed an issue where JSX and HTML converters would output a linebreak if the Lexical editor was empty
• Fixed a bug where setting hideInsertParagraphAtEnd to true did not hide the insert paragraph button
• Ensured inline blocks correctly store nested fields
• Fixed link and upload extra field drawers not rendering fields when collections had unrelated access control

Form State and Access Control Fixes

• Fixed missing id argument in access.read function executed within form state
• Fixed incorrect setting of data as doc in form state
• Fixed an issue where basePath was not passed through if a method was overridden
• Fixed missing find collection versions REST endpoint

UI Improvements

• Fixed many bugs in the WhereBuilder relationship select menu
• Fixed placement issues with sonner toasts
• Added focus outline for sort column buttons for better accessibility
• Fixed hard-coded API paths by using serverURL and routes.api
• Fixed custom block row labels not rendering properly

Other Fixes

• Fixed incorrect error logging in MongoDB adapter
• Fixed scheduled publish jobs not being deleted when documents are deleted
• Fixed UpsertArgs not being exported in payload
• Fixed TypeScript strictness issues in various packages

New Features

Multi-Tenant Plugin

A new @payloadcms/plugin-multi-tenant package has been added to provide a standardized approach to multi-tenancy in Payload. This plugin:

• Adds a tenant selector to the sidebar above navigation links
• Adds a hidden tenant field to specified collections
• Adds an array field to the users collection for tenant assignment
• Combines access control with tenant-based permissions
• Filters list views based on the selected tenant

Enhanced Upload URL Fetching

The pasteURL feature for Upload fields now supports both client-side and server-side URL fetching:

• By default, Payload will attempt to fetch files client-side directly in the browser
• Server-side fetching can be enabled by configuring an allowList of trusted domains
• A new /api/:collectionSlug/paste-url endpoint is used for server-side fetching
• This solves CORS issues when fetching files from external domains

JPEG XL Support

Added support for calculating and displaying file sizes for JPEG XL images.

View Context Exposure

The context of the view being rendered is now exposed on the server, providing:

• viewType - which view is being rendered (list, document, version, account, verify, reset)
• documentSubViewType - which sub-view is active (api, livePreview, default, versions)

New Integration Examples

• Added example for using Remix with Payload Local API
• Added example for using Astro with Payload Local API

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Form State Optimization

The form state response size has been significantly reduced by up to 3x, improving overall response times:

• Removed $undefined strings from properties like value, initialValue, and fieldSchema
• Removed unnecessary properties like empty errorPaths arrays and empty customComponents objects
• Removed properties like valid and passesCondition which only need to be returned if explicitly false
• Removed unused properties like isSidebar that can be calculated during render

Deep Copy Optimizations

Several optimizations were made to reduce unnecessary deep copying of data:

• Removed unnecessary deep copying from field hook operations
• Moved deep copy logic from the beforeValidate hook to the start of local API operations
• Ensured deep copying only runs for local API and not for GraphQL and REST operations
• Optimized the sanitizeInternalFields function to reduce shallow copying

List View and UI Optimizations

• Improved list view rendering speed by ensuring the root layout does not re-render when navigating to list view
• Removed duplicative client CollectionConfig data being sent to the client for every table cell
• Optimized getEntityConfig lookups by replacing array-based lookups with a map (O(n) to O(1))
• Replaced all instances of validOperators.includes with validOperatorMap[] (O(n) to O(1))
• Reduced unnecessary shallow copying within operations
• Removed unnecessary deleteMany call in deleteUserPreferences for auth-enabled collections
• Ensured unnecessary config translations are not sent to the client
• Removed undefined minRows and maxRows values from being sent to the client

Rich Text Optimizations

• Ensured internal link nodes do not store URL field, and vice versa, reducing data redundancy

Impact Summary

Payload CMS v3.18.0 delivers substantial performance improvements that will benefit all users, with form state response sizes reduced by up to 3x. This translates to faster page loads, more responsive admin interfaces, and reduced server load.

The new multi-tenant plugin is a game-changer for projects requiring content segregation across different tenants, eliminating the need for custom implementations and providing a standardized approach to multi-tenancy. This is particularly valuable for SaaS applications, multi-site CMSes, and enterprise deployments.

Enhanced upload capabilities with server-side URL fetching solve a common pain point where users couldn't paste URLs from external domains due to CORS restrictions. The new allowlist approach provides both flexibility and security.

Improved field validation error messages using field labels instead of paths make the admin interface more user-friendly, especially for content editors working with complex nested fields.

TypeScript strictness improvements across packages will help catch potential bugs earlier in the development process and provide better type safety for developers extending Payload.

The addition of examples for Remix and Astro integration showcases Payload's versatility as a headless CMS that can work with modern frameworks through its Local API.

Overall, this release focuses on performance, developer experience, and expanding Payload's capabilities for complex use cases while maintaining backward compatibility.

Full Release Notes