I couldn't find a guide like this, so I want to share my own experience.
It's not an ultimate guide to migration from Payload 1.x to 2.x, but rather a step-by-step account of my personal experience undertaking this migration.
Upgrade packages
Firstly, you need to upgrade your packages.
For the Payload itself, you need to upgrade to version 2.
yarn add payload@2.0.0
We're going to continue using MongoDB, so we need to install the MongoDB dependencies as well.
yarn add @payloadcms/bundler-webpack @payloadcms/db-mongodb @payloadcms/plugin-cloud @payloadcms/richtext-slate
Server
For the server setup, the only change is to remove the database initialization.
// server.ts: remove this line
mongoURL: process.env.MONGODB_URI,
Payload Configuration
For the payload.config.ts file, you need to import the new dependencies.
// payload.config.ts: Add these lines at the beginning of the file.
import { payloadCloud } from '@payloadcms/plugin-cloud'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { webpackBundler } from '@payloadcms/bundler-webpack'
import { slateEditor } from '@payloadcms/richtext-slate'
import { buildConfig } from 'payload/config'
In the build configuration, you need to add some settings.
export default buildConfig({
...
admin: {
...
bundler: webpackBundler(),
},
...
plugins: [payloadCloud()],
editor: slateEditor({}),
db: mongooseAdapter({
url: process.env.MONGODB_URI,
}),
});
Routes
I have some custom views. In version 1.1, the custom views are declared as an array, but now they are declared as an object. The name changes from "routes" to "views."
// before
export default buildConfig({
admin: {
...
components: {
routes: [
{
path: '/path/to/view',
Component: CustomReactComponent,
}
]
}
}
});
// after
export default buildConfig({
admin: {
...
components: {
views: {
CustomViewComponent: {
path: '/path/to/view',
Component: CustomReactComponent,
},
AnotherViewComponent: {
path: '/path/to/view',
Component: CustomReactComponent,
},
}
}
}
});
It will have other breaking changes that I couldn't write here. Please feel free to write about any other breaking changes you encountered in your project in the comments. Additionally, don't hesitate to ask for help if needed
Top comments (2)
Great write-up. We'll do a better job surfacing an upgrade guide for 3.0. Here are the release notes for 2.0, which can be used as a guide of sorts: github.com/payloadcms/payload/rele...
That guide would be so great right about now.