How to Upgrade from Payload CMS v3 to v4: A Step-by-Step Migration Guide

How to Upgrade from Payload CMS v3 to v4

Payload CMS v4 is in active public beta (currently at v4.0.0-beta.4, released October 22, 2026), bringing a completely redesigned admin UI, TanStack Start support, hierarchies, a rewritten MCP, and much more. This guide walks you through the official upgrade path.

What’s New in Payload CMS v4?

Redesigned Admin UI – A fresh, modern interface with improved accessibility, grid view, and a new activity widget
TanStack Start Support – Run Payload with TanStack Start in addition to Next.js, with up to 3x faster dev loads
Hierarchies and Tags – Organize content with parent-child relationships and tagging
Rewritten MCP – Enhanced AI-ready content framework capabilities
File Upload Versioning – Track and restore previous versions of uploaded files
Node.js 24.22.1 minimum – Requires Node.js 24.22.1 or newer

Prerequisites

Node.js 24.22.1 or higher installed
An existing Payload CMS v3 project
A backup of your database and project files
Git repository with a clean working state

Step 1: Back Up Your Project

Before anything else, create a full backup of your database and commit or stash any uncommitted changes in your git repository.

Step 2: Run the Official Codemod

Payload provides an automated codemod tool that handles the majority of breaking changes for you. Run it from your project root:

npx @payloadcms/codemod@beta upgrade

The codemod will automatically update your configuration files, rename deprecated APIs, and flag any manual changes required.

Step 3: Update Your Node.js Version

Payload v4 requires Node.js 24.22.1 as a minimum. Update your runtime using nvm or your preferred version manager, and update your .nvmrc file and CI/CD pipeline configurations.

Step 4: Install the Beta Package

npm install payload@beta

If you are using the Next.js adapter, also run: npm install @payloadcms/next@beta

Step 5: Review Breaking Changes

Key breaking changes to address manually:

Nodemailer 10 – If you pass a custom transport, upgrade nodemailer to ^10 and remove @types/nodemailer
TanStack Start – Update to @tanstack/react-start ^1.169.1 and @tanstack/react-router ^1.170.44
Deprecated APIs removed – Check the official v4 migration guide for the full list
Global version restoration – Behavior now aligns with collections
Diff component props – Renamed to valueFrom and valueTo

Step 6: Test Your Application

Run your development server and test suite. Pay special attention to admin UI functionality, API endpoints, authentication flows, rich text editor content, and any custom plugins or adapters.

Step 7: Update Your Deployment Configuration

Ensure your hosting environment supports Node.js 24.22.1+. Update your Dockerfile, Vercel, Railway, or Render configuration accordingly.

Staying on v3? Use v3.92.0

If you are not ready to migrate to v4 yet, Payload v3.92.0 (also released October 22, 2026) is the latest stable release. It backports important security fixes and requires Node.js 22.23.4 as a minimum.

Key Takeaway: The official codemod handles most of the heavy lifting for the v3 to v4 migration. Start with a clean git state, run the codemod, address the remaining breaking changes manually, and test thoroughly before deploying to production.

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

Resources: