All the new stuff in this version has been released as canary for over three weeks now, where we've been vigorously testing and monitoring the new features and performance improvements that come with the release. This release reflects the Payload team thinking years into the future about where we want to be as a CMS and an app framework.

It has more than just new features and DX improvements. It's got a substantial set of refinements to the inner-workings of Payload, making it more suited to ambitious goals of ours such as being able to deploy serverlessly on hosts like Vercel and Netlify, significantly improve our TypeScript dev experience, and a lot more.

Many of this release's changes take place behind-the-scenes, and some come with some potentially breaking changes, but the next few months are going to make it even more clear that Payload is the best and most modern CMS available.

Massive TypeScript improvements

The biggest thing that this release ships is a dramatic improvement to our TS developer experience. Before, our Local API was typed as generic functions - meaning to get strong typing, you'd need to pass in your generated type. A bit of manual labor.

Before 1.6.0:

1import payload from 'payload';
2import { Page } from './payload-types';
3
4// Note how you used to need to manually pass in `Page`
5const page = await payload.findByID<Page>({
6  // the 'collection' property was only typed as 'string' before
7  collection: 'pages',
8  id: 'some-id-here',
9})

But now, Payload automatically types all of its local API methods—they no longer require you to pass types to generic functions. It's just done for you. And the typing has become significantly stronger.

1import payload from 'payload';
2
3// The resulting `page` will now be typed for you,
4// corresponding to your config shape.
5// No more needing to pass a type to the generic!
6const page = await payload.findByID({
7  // the 'collection' property is now typed strongly
8  // and allows only your available collections
9  collection: 'pages',
10  id: 'some-id-here',
11})

There is some pretty awesome TS magic happening behind the scenes to make this happen. Thanks to community member and Payload contributor Kalon-Robson of Innovixx for helping out here! We pinged our Discord #contributors channel for a little community brainstorming and Kalon-Robson came back within like 10 minutes with a super nice solution for how to make that magic happen.

Each one of Payload's Local API methods are now automatically typed like this. In the future, we'll continue to expand on this new pattern in an effort to keep these DX improvements going.

To opt into using the new TypeScript improvements, you need to generate TypeScript interfaces, and then update your tsconfig.json with a new path like this:

1{
"compilerOptions": {
  // your compilerOptions here
  "paths": {
    // Tell TS where to find your generated types
    // This is the default location below
    "payload/generated-types": ["./src/payload-types.ts"]
  }
}
10}

Optimized Local API

In addition to optimizing the TypeScript interface of the Local API, the entire API has gotten a significant overhaul. We've reduced down a barebones Payload class in order to make it as small as possible for deploying in a serverless context. Now, the Local API no longer includes any imports to anything HTTP-related (Express, GraphQL, etc.) and only exposes methods to interact with your database, meaning that it can be deployed in as small of a serverless function bundle size as currently possible.

We're trying to reduce cold-start times for Lambda functions and in the future we're aiming at even being able to deploy to edge functions.

Outside of the TS changes above, the way you interact with the Local API has not changed, and all of these optimizations have taken place completely behind the scenes.

Faster startup / transpilation times

Speaking of cold starts, if you've been around for the last few months, you've likely taken note of our recent efforts to move from babel to swc for config transpilation. We have been investing time in improving Payload startup time by leveraging the most modern transpilation tactics available, and this release takes our efforts a step further by reducing some transpilation duplication that was present within Payload. Now, Payload no longer transpiles your config for you within the framework itself. Instead, we just rely on your own TypeScript transpilation to handle things like JSX and modern syntax in your project.

You probably already used something like ts-node anyway, which made our internal reliance on swc fairly duplicative. So we figured we'd just let you handle the transpilation in development mode.

This comes with some pretty awesome benefits like improving cold start times, reducing Lambda function bundle sizes, and reducing complexities within Payload itself.

Simplified Versions logic

This release removes over 600 lines of code for our versions and drafts implementation, reflecting a dramatic streamlining of the logic that Payload featured to support these features. We've invested some serious time to remove some of the bug-prone complexities of Payload, make versions and drafts work more performantly and predictably, and ensure that Payload is compatible with older versions of Mongo, DocumentDB, and Azure Cosmos MongoDB.

In addition, this simplification sets us up for additional database support in the future by detaching Payload from some of its close connections to Mongo functionality that is only compatible with the newest versions.

Other features & optimizations

In addition to the above improvements, this release ships with a ton of new features across the board. Here are just a few notable updates:

Improved fallback locale handling, including more intelligently falling back to empty text fields, rich text, etc.
The blocks field selector now utilizes our new Drawer UI to give editors a better experience when adding new blocks to a layout
Implements loading UI across the entirety of the admin UI
Ships a new JSON field type, which we'll be talking about in further depth soon

Breaking changes

We've got a comprehensive writeup for how to tell if you will be affected by these breaking changes in our Changelog, so make sure to check the release notes and follow along with the instructions there.

Like what we're doing? Give us a star on GitHub

We're trying to change the CMS status quo by delivering editors with a great experience, but first and foremost, giving developers a CMS that they don't absolutely despise working with. All of our new features are meant to be extensible and work simply and sanely.

Get up and running with one line

Getting started with Payload is easy—and free forever. Just fire up a new terminal window and run the following command:

1npx create-payload-app