TL;DR

Payload CMS v0.13.0 introduces TypeScript type generation, relationship filtering, improved querying capabilities, and custom field onChange handlers. This release significantly enhances developer experience with better TypeScript support, more powerful querying options, and greater flexibility in form handling. It also includes important bug fixes for uploads, relationships, and query parameters.

Highlight of the Release

• TypeScript type generation for collections, fields, and operations
• Relationship filtering for better content querying
• Custom onChange handlers for text, select, and upload fields
• Azure Cosmos DB compatibility
• Improved querying logic with better support for complex queries
• Async preview URLs for more flexible content previews

Migration Guide

Migrating to v0.13.0

TypeScript Users

If you're using TypeScript, you'll now benefit from auto-generated types. You may need to update your imports to use these types:

import { CollectionConfig } from 'payload/types';
// Use the generated types for your collections
import { Post } from 'payload/generated-types';

Field Component Changes

The useFieldType hook has been renamed to useField. If you're using this hook in custom field components, update your imports and usage:

// Old
import { useFieldType } from 'payload/components/forms';
// New
import { useField } from 'payload/components/forms';

Custom onChange Handlers

If you want to leverage the new custom onChange handlers for text, select, or upload fields, you can now pass an onChange prop:

{
  name: 'myTextField',
  type: 'text',
  onChange: (value, { field, form }) => {
    // Custom handling here
    return value; // Return the value to be set
  }
}

Preview URLs

If you're using preview URLs, you can now return either a string (sync) or a Promise that resolves to a string (async):

{
  admin: {
    preview: (doc) => {
      // Synchronous
      return `https://mysite.com/preview/${doc.slug}`;
      
      // Or asynchronous
      return fetch('/api/get-preview-url', {
        method: 'POST',
        body: JSON.stringify({ id: doc.id }),
      }).then(res => res.json()).then(data => data.url);
    }
  }
}

Upgrade Recommendations

This is a minor version update with significant new features but no breaking changes. We recommend all users upgrade to v0.13.0 to benefit from the TypeScript improvements, enhanced querying capabilities, and numerous bug fixes.

How to Upgrade

1. Update your Payload dependency in package.json:

   "payload": "^0.13.0"
   

2. Run npm install or yarn to update to the new version

3. If you're using TypeScript, review the new type generation features and update your code to leverage the improved type safety

4. Test your application thoroughly, especially if you rely heavily on relationship queries or upload functionality

No database migrations are required for this update.

Bug Fixes

Query and Relationship Fixes

• Fixed issue with querying by ID using comma-separated values
• Ensured 'like' query parameter remains functional in all cases
• Fixed bug with relationship cell when no document is available
• Ensured relationship field search can return more than 10 options
• Fixed querying by relationship subpaths
• Ensured non-localized relationships with many relationTos can be queried properly
• Improved buildQuery to work with fields as well as simultaneous OR/AND conditions

Upload and Media Fixes

• Fixed issue #358 with reuploading files with existing filenames
• Ensured uploads can be fetched with CORS enabled
• Added WebP support for admin dashboard thumbnail component

UI and Formatting Fixes

• Ensured richtext links retain proper formatting
• Updated field description type to include React nodes
• Fixed typing for collection description

New Features

TypeScript Type Generation

Payload now automatically generates TypeScript types for your collections, fields, and operations. This provides better type safety and developer experience when working with Payload in TypeScript projects.

Relationship Filtering

A new relationship filter field has been added, allowing for more powerful filtering of related content. This makes it easier to find and manage relationships between documents.

Custom onChange Handlers

Text, select, and upload fields now support custom onChange handlers, giving developers more control over form behavior and data manipulation.

Azure Cosmos DB Compatibility

Payload now works with Azure Cosmos DB, expanding the database options available for your projects.

Async Preview URLs

The admin preview functionality has been migrated to support both synchronous and asynchronous preview URLs, providing more flexibility in how content previews are generated.

Enhanced Access Control

Update hooks now have access to full original documents even when access control is in place, and upload access control is now applied to all auto-generated image sizes.

Security Updates

Upload Access Control

Upload access control is now properly applied to all auto-generated image sizes, ensuring that access restrictions are consistently enforced across all variations of uploaded images.

Performance Improvements

Query Performance

The querying logic has been improved, which should result in more efficient database operations, especially for complex queries involving relationships and filters.

Indexed Filenames

Filenames are now indexed, which should improve performance when searching for or accessing files by name.

Optimized BuildQuery

The buildQuery functionality has been optimized for better legibility and performance, making complex queries more efficient and easier to debug.

Impact Summary

Payload CMS v0.13.0 represents a significant step forward for TypeScript users with the introduction of automatic type generation, making development more type-safe and productive. The improved querying capabilities, relationship filtering, and custom onChange handlers provide developers with more powerful and flexible tools for building complex applications.

The Azure Cosmos DB compatibility expands deployment options, while numerous bug fixes address issues with uploads, relationships, and query parameters that users may have encountered in previous versions.

This release balances new features with important stability improvements, making it a recommended upgrade for all Payload users. TypeScript developers will see the most immediate benefits, but the enhanced querying, relationship filtering, and bug fixes will improve the experience for all users regardless of their development stack.

Full Release Notes