Payload CMS Release: 3.5.0

TL;DR

Payload CMS v3.5.0 brings significant updates including React 19 stable and Next.js 15.0.4 support, relative URL capabilities for dynamic preview deployments, improved field behaviors, and various bug fixes. This release enhances developer experience with exported utility functions, better array field handling, and MongoDB security improvements. Template improvements focus on seed script performance and UI enhancements.

Highlight of the Release

• React 19 stable and Next.js 15.0.4 support with simplified type configuration
• Relative URL support for dynamic preview deployments (especially useful for Vercel)
• MongoDB security improvement with mongoose 8.8.3 update
• Fixed array field collapse behavior during input changes
• Improved template seeding performance

Migration Guide

Upgrading to React 19 Stable and Next.js 15.0.4

To upgrade your existing project to React 19 stable and Next.js 15.0.4, update the following in your package.json:

  "dependencies": {
-    "next": "15.0.3",
+    "next": "15.0.4",
-    "react": "19.0.0-rc-66855b96-20241106",
-    "react-dom": "19.0.0-rc-66855b96-20241106",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
     ...
  },
  "devDependencies": {
-    "@types/react": "npm:[email protected]",
-    "@types/react-dom": "npm:[email protected]",
+    "@types/react": "19.0.1",
+    "@types/react-dom": "19.0.1",
  },
-  "pnpm": {
-    "overrides": {
-      "@types/react": "npm:[email protected]",
-      "@types/react-dom": "npm:[email protected]"
-    }
-  },
-  "overrides": {
-    "@types/react": "npm:[email protected]",
-    "@types/react-dom": "npm:[email protected]"
-  }

After updating your dependencies, run your package manager's install command:

# For npm
npm install

# For yarn
yarn

# For pnpm
pnpm install

No other code changes should be necessary as this is primarily a dependency update.

Upgrade Recommendations

This release is recommended for all users as it includes important security updates, performance improvements, and bug fixes.

Priority by User Type:

• High Priority for Vercel Users: If you're deploying to Vercel and using preview deployments, this update significantly improves the preview experience with relative URL support.
• High Priority for MongoDB Users: The mongoose security update addresses a potential vulnerability.
• Medium Priority for All Other Users: The React 19 stable update and UI improvements provide a better development and user experience.

Upgrade Steps:

1. Update your Payload dependencies to v3.5.0
2. If using React and Next.js, follow the migration guide to update to React 19 stable and Next.js 15.0.4
3. Test your application thoroughly, especially if you're using features that were fixed in this release (array fields, join fields, nested population)

The upgrade should be straightforward with minimal risk of breaking changes.

Bug Fixes

UI Improvements

• Array Field Collapse Behavior: Fixed an issue where array fields with initCollapsed: true would auto-collapse when typing in their inputs during creation of new items
• Join Field Configuration: Join fields now properly respect the defaultSort and defaultLimit configurations from both field and collection settings
• Group Field Labels: Corrected the label size for group fields by rendering them as spans instead of labels
• Header DOM Node Rendering: The <header> DOM node for group fields now only renders when needed (when label, description, or errors are present), preventing extra margin when empty
• Locale Value Handling: Fixed stale locale values from useLocale by memoizing the locale instead of relying on useEffect
• Document Submenu: Disabled document submenu when the parent button is disabled for better UX

Database and Data Handling

• MongoDB Security: Updated mongoose to version 8.8.3 to address security vulnerability CVE-2024-53900
• Postgres Select Query: Fixed handling of select query on select fields in Postgres/SQLite databases
• Nested Population: Fixed issues with defaultPopulate and populate when defining nested properties in arrays and blocks
• Import Map Generation: Fixed getPayload to generate import map only when used in Payload Admin Panel, preventing errors in projects without Next.js

New Features

React 19 Stable and Next.js 15.0.4 Support

Payload now fully supports React 19 stable and Next.js 15.0.4. This eliminates the need for type overrides in your project configuration, simplifying your package.json setup. The update removes the requirement for pnpm.overrides and overrides keys that were previously needed for React 19 RC compatibility.

Relative URL Support for Dynamic Preview Deployments

Two new features have been added to support relative URLs for dynamic preview deployments:

• Live Preview: Now supports relative URLs, which is particularly useful for Vercel preview deployments where URLs are dynamically generated
• Next.js Preview: Similar support for relative URLs in admin.preview configuration

This solves the problem of preview deployments breaking due to dynamically generated URLs, as Payload can now prepend the application's top-level domain at render-time.

Global Label as Function

You can now define global labels as functions, providing more flexibility in how labels are generated and displayed.

Exported Utility Functions

The following utility functions are now exported from the main Payload package:

• sanitizeSelectParam
• sanitizePopulateParam
• senitizeJoinParams

These functions were previously only available internally or in the Next.js package but are now accessible for use in custom endpoints and other external implementations.

Security Updates

MongoDB Vulnerability Fix

The MongoDB driver (mongoose) has been updated to version 8.8.3 to address security vulnerability CVE-2024-53900. While Payload doesn't use the vulnerable $where property in its queries, this update protects users who might access mongoose directly via payload.db.collections.

Admin Route Protection

The website template now includes a robots.txt configuration that disallows crawling of the /admin route, adding an extra layer of protection for admin interfaces.

Performance Improvements

Template Seeding Performance

Multiple improvements have been made to enhance the speed of seed scripts:

• The website template seed script has been optimized by moving operations to be async
• Revalidation has been disabled during seeding operations to improve performance
• Specific improvements for PostgreSQL database seeding in the website template

CI/CD Pipeline Optimizations

Several CI/CD pipeline improvements have been implemented:

• Main workflow has been refactored to take advantage of re-usable node/pnpm setup actions
• Tests now only run when needed via a needs_tests filter
• Explicit use of Ubuntu 24.04 instead of latest to ensure compatibility
• Various other workflow improvements to speed up build and deployment processes

Impact Summary

Payload CMS v3.5.0 delivers significant improvements across multiple areas, with the most notable being the upgrade to React 19 stable and Next.js 15.0.4. This eliminates the need for complex type overrides that were previously required, streamlining project configuration.

The addition of relative URL support for dynamic preview deployments is particularly valuable for teams using Vercel, as it solves a common issue where preview deployments would break due to dynamically generated URLs. This feature ensures that live preview and admin preview functionality work correctly in all deployment environments.

Security has been enhanced with the mongoose update to address a potential vulnerability, while numerous UI fixes improve the content editing experience. The array field collapse behavior fix is especially important for content editors working with complex nested data structures.

Performance improvements to template seeding will benefit new projects and development workflows, making initial setup faster and more efficient. The exported utility functions provide developers with more flexibility when building custom endpoints and integrations.

Overall, this release balances new features with important bug fixes and performance improvements, making it a recommended upgrade for all Payload CMS users.

Full Release Notes

...
  "dependencies": {
-    "next": "15.0.3",
+    "next": "15.0.4",
-    "react": "19.0.0-rc-66855b96-20241106",
-    "react-dom": "19.0.0-rc-66855b96-20241106",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
     ...
  },
  "devDependencies": {
-    "@types/react": "npm:[email protected]",
-    "@types/react-dom": "npm:[email protected]".
+    "@types/react": "19.0.1",
+    "@types/react-dom": "19.0.1",
  },
-  "pnpm": {
-    "overrides": {
-      "@types/react": "npm:[email protected]",
-      "@types/react-dom": "npm:[email protected]"
-    }
-  },
-  "overrides": {
-    "@types/react": "npm:[email protected]",
-    "@types/react-dom": "npm:[email protected]"
-  }