What’s up everyone? In this guide, I'm going to upgrade our Payload CMS instance from 3.11 to 3.18. I’ll highlight important new features and bug fixes and troubleshoot as we go. Now, let’s dive in.
3.12
Currently, our project is on 3.11, so we’ll go to our package.json file and move all of our dependencies from 3.11 to 3.12. We can run pnpm i to install the new version.
Note
You can also just run pnpx payload-create-app to upgrade all your Payload dependencies automatically to the most recent version. The script will check that Payload is already installed in your project.
The key things I want to highlight here are the scheduled publish / unpublish feature and filterOptions arg addition of req. In 3.12, the publish/unpublish feature was unfinished as it didn’t allow you to delete an unpublished event, but that issue has since been fixed in a newer version. In order to enable this feature, you will need to enable drafts in your collection by adding versions.drafts.schedulePublish: true.
You can also now include req to filterOptions, which allows you to access payload, user, and locale in your filterOptions.
There are also a couple of useful features and bug fixes for those who use postgres and markdown for their projects.
3.13
Next, we’ll move up to version 3.13 by updating all of our payload dependencies to 3.13 and running pnpm i. In this version, you gain more control over how to disable graphql, a new translation, and the ability to use onMount in your code fields. The feature I want to focus on here, though, is the ability to override the lexical default placeholder.
You can do this by going to any of your initialized lexicalEditors and adding an admin option, which takes a string placeholder. That string can be whatever you want it to be to make it more useful for your editors.
There are several bug fixes that I would recommend reading through, but nothing that jumps out to me as a common problem.
I will call out those that this version introduced an update to the documentation to include a rather robust example of building a custom feature in Lexical.
3.14
Next up is 3.14. This version is light on features with just one feature to add Estonian language support.
In bug fixes, there was some work done to make sure access restrictions were respected in scheduled publish/unpublish documents and the save button is now disabled until the upload of a file is ready.
Most importantly, this version fixes an error in JSX rendering of internal links by defining internalDocToHref, which gets rid of a TypeScript error as seen in my guide about rendering Lexical content on the frontend.
3.15
3.15 is again light on features but big on bug fixes, we can update our dependencies to 3.15 and run pnpm i. A few quality of life features were included, like a specific warning about missing storage adapters on upload collections.
You’re now allowed to set maxDepth to "0" in your join fields. If you don’t need to access relationships in your join fields, it’s recommended you do this to reduce the amount of data sent to your frontend.
You’re now able to add reply_to to the API when sending emails from Resend. To see how to set up Resend to take care of your emails, read my guide on setting up the PayloadCMS email adapter. The reply_to field allows you to change who the person replies to when responding to emails.
You’re now able to disable the div container that comes with the RichText serializer that Payload provides. Simply add disableContainer: true to your RichText component to remove the div. This comes in handy for when you provide your own container around the RichText serializer.
3.15.1 came out shortly after 3.15 but nothing of note was included aside from a few bug fixes.
3.16
Now let’s update to 3.16 and run pnpm i.
A few new features came out with 3.16 including the consolidation of REST API handling and the ability to autoRun jobs.
For bug fixes, we’re now able to schedule publish before saving a draft, which just adds more flexibility to the publish/unpublish feature.
There were also several documentation updates, including an update around the beforeValidate documentation.
3.17.1
Next is 3.17.1. 3.17 produced errors for some users, so it’s not worth installing and showing, but we’ll still go over the features and bug fixes. So, update all dependencies to 3.17.1 and run pnpm i.
In this version, we’re now able to delete our scheduled published documents. So, if you enabled those back in 3.12, you can now delete items you’ve added for the future.
You can also now see a new paragraph button below your Lexical Rich Text editor. This version also updates the version of lexical, which is where the error came from in 3.17. The error doesn’t persist in 3.17.1.
For bug fixes, the placeholder in lexical rich text fields had incorrect padding at small screen sizes, so that’s been fixed.
3.18
That lands us on 3.18, which is the most recent version as of the time of this recording. We’ll update everything from 3.17.1 to 3.18 and run pnpm i.
This version introduced new features like jpeg XL image size calculation and adding jsx and html converters for tab nodes. There’s also a new multi-tenant plugin that was added in this version. There are also new examples added that show Payload’s Local API being used with Remix and Astro.
Key bug fixes include things like scheduled publish jobs are now deleted when the document is deleted. The hideInsertParagraphAtEnd option for Lexical Rich Text now works. Before, it didn’t actually hide the paragraph button.
Final Thoughts
And that’s it for this upgrade guide. As you can see, the Payload CMS team is still hard at work adding new features and fixing bugs as they appear. These changes all took place in the span of about 3 weeks, so I know we can expect much more to come in the near future.
