How to Prepare Your Next.js App for Payload CMS 4.0

Payload CMS 4.0 is actively in canary development (the latest canary build is v4.0.0-canary.38, released October 7, 2026), and it brings sweeping architectural changes that will affect every Payload project. While there is no official stable release date yet, the team was targeting a beta within the next quarter as of June 2026. Now is the perfect time to start preparing your codebase so the migration is smooth when 4.0 lands.

Here is a step-by-step guide to getting your Payload 3.x project ready for the jump to 4.0.

Step 1: Upgrade to Payload 3.90.x First

Before thinking about 4.0, make sure you are on the latest stable branch. Payload 3.90.0 (released September 18, 2026) included a critical batch of security fixes and the team strongly urged all users to upgrade immediately. The latest stable is 3.90.2.

npm install payload@latest

After upgrading, regenerate your TypeScript types and, if you are using a SQL database, create and run a migration:

npx payload generate:types
npx payload migrate:create
npx payload migrate

Step 2: Migrate from Slate to Lexical

Payload 4.0 drops the Slate rich text editor entirely. Lexical is the only supported editor going forward. If you are still using Slate in any of your collections, migrate to Lexical now. The official migration guide explicitly states: do not upgrade to 4.0 until you have completed this step.

import { lexicalEditor } from '@payloadcms/richtext-lexical'

{
  name: 'content',
  type: 'richText',
  editor: lexicalEditor({})
}

Step 3: Set overrideAccess Explicitly in All Local API Calls

One of the most impactful breaking changes in 4.0 is that the Local API now enforces access control by default. In 3.x, overrideAccess defaults to true, meaning server-side calls bypass your access rules. In 4.0, it defaults to false. Audit every Local API call in your codebase and add overrideAccess: true where you intentionally want to bypass access control.

const posts = await payload.find({
  collection: 'posts',
  overrideAccess: true,
})

Step 4: Set depth Explicitly in Your Queries

In 4.0, the default query depth changes from 2 to 1. This means relationship fields will only populate one level deep by default. To avoid unexpected undefined values after upgrading, set depth explicitly in all your queries today:

const post = await payload.findByID({
  collection: 'posts',
  id: postId,
  depth: 2,
})

Step 5: Update Your Node.js, Next.js, and TypeScript Versions

Payload 4.0 raises the minimum requirements significantly:

Node.js: 24.15 or higher (up from 18.20.2)
Next.js: 16.4 or higher
TypeScript: 6.0.3 or higher

Start testing your project against these versions in a staging environment now to surface any compatibility issues early.

Step 6: Review Background Job Permissions

Payload 3.89 backported a 4.0 change: background jobs now apply access control by default. Review your task definitions and ensure any jobs that need elevated permissions are configured accordingly.

Step 7: Run the Codemod on a Staging Branch

Payload provides an official codemod tool that automates most of the 4.0 migration. Run it on a separate branch to see what changes are needed:

npx @payloadcms/codemod

The codemod is safe to run multiple times on a partially migrated project. It handles the bulk of the mechanical changes, but you will still need to review the output and handle any custom logic manually.

Step 8: Watch the Canary Releases for Beta Signals

The latest canary (v4.0.0-canary.38, Oct 7) added significant features including LLM instructions management in the admin panel, file transformers with upload variants, a new database copy method, batch processing foundations, and a rebuilt navigation and account menu. These signal that the feature set is stabilising. Keep an eye on the official GitHub releases for the beta announcement.

Key Takeaway: Payload 4.0 is a significant but well-signposted migration. The team has provided a codemod, a detailed migration guide, and has been backporting key behavioral changes to 3.x to ease the transition. Start with Steps 1 to 4 today as they are safe to do on your production codebase right now and will make the eventual 4.0 upgrade far smoother.

Hashtags: #PayloadCMS #NextJS #WebDevelopment #HeadlessCMS #TypeScript #JavaScript #CMS

Resources: