The best way to build a modern backend + admin UI. No black magic, all TypeScript, and fully open-source, Payload is both an app framework and a headless CMS.
MIT License
Bot releases are visible (Hide)
Published by denolfe about 1 year ago
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
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
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:
npm run payload migrate
And you'll be all good!
This change should only affect you if you have a custom array / block validation defined.
For 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.
Pretty self-explanatory on this one. Node 14 is old.
If you don't have anything custom with the Pino logger, this does not apply to you.
MongoDB 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.
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.
These 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'
}
}]
}
}
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
],
},
}),
};
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!
Published by denolfe about 1 year ago
Published by denolfe about 1 year ago
Published by denolfe about 1 year ago
Published by jmikrut about 1 year ago
Published by denolfe about 1 year ago
force
parameter to prevent false negation; (#3278) (429a88a)Published by jmikrut about 1 year ago
Published by DanRibbens about 1 year ago
Published by DanRibbens about 1 year ago
Published by DanRibbens about 1 year ago
Published by denolfe about 1 year ago
Published by denolfe about 1 year ago
Published by jmikrut about 1 year ago
Published by DanRibbens about 1 year ago
Published by DanRibbens about 1 year ago
Published by jmikrut about 1 year ago