rtl, human-friendly labels, etc.tsconfig path pointing to your generated Payload types is no longer required for types to workHere's an example of a barebones Payload config, set up to work as 1.0 did:
import { mongooseAdapter } from "@payloadcms/db-mongodb";
import { slateEditor } from "@payloadcms/richtext-slate";
import { webpackBundler } from "@payloadcms/bundler-webpack";
import { buildConfig } from "payload/config";
export default buildConfig({
admin: {
bundler: webpackBundler(),
},
editor: slateEditor({}),
collections: [
// your collections here
],
db: mongooseAdapter({
url: process.env.DATABASE_URI,
}),
});
These new properties are all now required for Payload to function, and you will have to install each separate adapter that you use. Feel free to swap out any of the adapters with your choice (Lexical, Postgres, Vite, etc.)
Make sure to install the packages that you need. In the above example, you would need to install the following:
npm install --save @payloadcms/db-mongodb @payloadcms/richtext-slate @payloadcms/bundler-webpack⚠️ Draft versions now require a
latest: true property to be set on the most recent draft in your _versions collections(s)
We have a ready-to-go migration script for your versions from v1 to v2, and to use it, all you have to do is run the following commands:
1. First, make sure you have a payload npm script in your package.json
{
"scripts": {
"payload": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload"
}
}
Adjust the PAYLOAD_CONFIG_PATH to point to your Payload config file if necessary.
2. Create a migration, using the new Payload migration API
yarn payload migrate:create --file @payloadcms/db-mongodb/versions-v1-v2 # or npm, note the use of `--` npm run payload migrate:create -- --file @payloadcms/db-mongodb/versions-v1-v2
The above command will output a migration file into your ./src/migrations folder (default migrations location). It contains a migration script to automatically add a latest: true flag to each of your newest drafts, for all draft-enabled collections. It works out of the box!
3. Run migrations
From there, you need to run migrations. Run the following command to execute your new migration:
And you'll be all good!
⚠️ Array and block field validations now accept the full array of field data as their validation argument instead of the value.lengthThis change should only affect you if you have a custom array / block validation defined.
⚠️ For MongoDB, all models have been moved from the Payload object to the database adapterFor example, if you are leveraging Mongoose models directly, in 1.0, you would have accessed them via payload.collections[myCollectionSlug].Model. Now, you can access the Mongoose model from payload.db.collections[myCollectionSlug].
Version models can be accessed from payload.db.versions[myEntitySlug], and the global model can be accessed via payload.db.globals.
We don't have a migration ready to go yet for user preferences, and this typically wouldn't be a big deal for most Payload projects. So don't let it stop you from updating unless you have a serious amount of user preferences that you'd like to keep. If so, we'll come up with a migration script for you and hook you up. Just reach out to us on Discord to ask for this.
⚠️ Node 16 is now the minimum required node version and Node 14 is no longer supportedPretty self-explanatory on this one. Node 14 is old.
⚠️ The Pino logger has been updated, which may require you to make changes to your Pino config if you have a custom oneIf you don't have anything custom with the Pino logger, this does not apply to you.
⚠️ Transactions are now enabled by default if your database supports themMongoDB requires a replica set for transactions to work, so they likely are not going to work for you unless you do indeed have a replica set configured. But if you do, transactions will now instantly work for all internal Payload operations.
This means that in some fringe cases, if you are creating a doc and then instantly trying to update it within an afterChange hook, the newly created doc may not truly exist yet. This should not cause any problems for 99% of projects, but if you think this applies to you, might be good to double-check through your code.
To avoid any issues, you can pass the req.transactionID through to your Local API calls, so that your Local API calls are included as part of the parent transaction.
Payload's locales have become more powerful and now allow you to customize more aspects per locale such as a human-friendly label and if the locale is RTL or not.
This means that certain functions now return a different shape, such as useLocale. This hook used to return a string of the locale code you are currently editing, but it now returns an object with type of Locale.
The revisions we've made in 2.0 required changes to both HTML and CSS within the admin panel. For this reason, if you were loading custom CSS into the admin panel to customize the look and feel, your stylesheets may need to be updated. If your CSS is targeting elements on the page using HTML selectors or class names, you may need to update these selectors based on the current markup. It may also be necessary to update your style definitions if the core Payload component you are targeting has undergone significant change.
In many cases, our classnames and structure have remained the same, but technically, this could be a breaking change.
⚠️ Custom admin views API has changedThese changes only affect apps that are using custom views via the admin.components.routes config.
The type AdminRoute was renamed to AdminViewConfig. Simply update your instances with this new type and it will continue to work as expected. The properties of this type have not changed.
The admin.components.routes config has been merged with admin.components.views. Simply move your custom views to the views object. The properties of the config have not changed. Here is an example:
Previous:
admin: {
components: {
routes: [
{
Component: MyCustomView,
path: "/custom-view",
},
];
}
}
Current:
admin: {
components: {
views: {
MyCustomView: {
Component: MyCustomView,
path: '/custom-view'
}
}]
}
} ⚠️ Rich text admin properties have moved
If you have customized the Slate rich text editor via admin.elements or admin.leaves properties, you now need to add your customizations to a slateEditor({ admin: {} }) property. The signatures are all the same, but you might have to move some properties around.
Previous:
const myRichTextField: Field = {
name: "content",
type: "richText",
admin: {
elements: [
"h1",
"link",
// etc
],
},
};
Current:
import { slateEditor } from "@payloadcms/richtext-slate";
const myRichTextField: Field = {
name: "content",
type: "richText",
editor: slateEditor({
// Move the admin property as shown below
admin: {
elements: [
"h1",
"link",
// etc
],
},
}),
}; ⚠️ MongoDB connection options have been removed from payload.init
To pass connection options for MongoDB, you now need to pass them to db: mongooseAdapter({}) instead of passing them to payload.init().
If you are importing types from Payload, some of their locations may have changed. An example would be Slate-specific types being no longer exported from Payload itself—they are now exported from the @payloadcms/richtext-slate package.
That's it! Most of these changes will be instantly apparent to you thanks to TypeScript, and many may not apply to you at all. But this list should be comprehensive and we will do our best to keep everything up-to-date here accordingly. There are inevitably some types that have changed locations, and similar things like that, but overall, you should be able to swing the breaking changes and get updated.
If you need a hand, reach out on Discord and we will hook you up!
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4