PayloadCMS: V2 Migration guide

Fabio Soares — Wed, 14 Feb 2024 16:48:11 +0000

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

Forem: Fabio Soares

PayloadCMS: V2 Migration guide

Upgrade packages

Server

Payload Configuration

Routes