Skip to content
techpotions
Payload CMS · cms migration · nextjs · payload adminNovember 18, 20265 min read

Update Payload CMS Without Breaking Admin

A dry-run upgrade path for Payload CMS major versions: copy the database to staging, run the codemod, then audit admin overrides, adapters, and plugins before touching production.

Cover illustration for “Update Payload CMS Without Breaking Admin”

How to update payload cms across a major version without breaking the admin panel is less about which command to run and more about what you rehearse before you run it. Payload's own migration overview describes the 3.0 release as a complete replatform of the Admin Panel from a React Router single-page application onto the Next.js App Router — which means 'upgrading' is the polite word for what is, in practice, a frontend migration with a database attached. The upgrade that doesn't break the admin is the one you've already run twice on a copy of production.

How to Update Payload CMS: Rehearse Before You Run

The dry-run path has five stages: pin the old release, copy the database, run the codemod, re-audit every custom admin surface and plugin, then cut over with a fallback. Skipping straight to the codemod is how you find out a custom admin route is gone while a user is mid-edit.

Pin Versions and Copy the Database First

Rollback beats debugging. If you haven't got a byte-for-byte copy of the production database on staging, you are not doing a migration — you're running a live experiment. Pin your current Payload release exactly in package.json, drop the caret, then dump the database.

Text
pg_dump $PROD_DATABASE_URL > prod.dump
psql $STAGING_DATABASE_URL < prod.dump
Text
mongodump --uri=$PROD_MONGO_URI --out=./dump
mongorestore --uri=$STAGING_MONGO_URI ./dump

Run the Codemod, Then Read What It Changed

Payload ships a codemod for major-version config changes — run it, then read the diff like it was written by an intern.

Text
npx @payloadcms/codemod --transform <transform-name>

Treat every changed file as a claim, not a conclusion. A codemod rewrites the mechanical parts. It does not know your custom field validation or your bespoke access-control functions.

The Admin Replatform Is the Whole Migration at 3.0

If you're crossing 2.x to 3.x, the admin panel is not a CSS change. The 3.0 Admin Panel is a full replatform onto the Next.js App Router — everything you assumed about the admin being a client-side SPA stops being true. Components now sit on a server/client boundary, routing lives in the App Router, and a custom admin route that worked as a SPA can 404 in the new layout.

Audit Every Admin Component Override Before You Merge

Custom admin components are where upgrades quietly fail. The database can be perfectly healthy while a custom approve button renders as a blank card. Check every custom view and route registered in the admin config, every overridden field component, anything importing admin internals instead of the exported API, and any component touching browser APIs that now needs a client directive.

Update Config and DB Adapters in One Pass

Adapter and config changes usually ride along with the codemod, but verify them by hand — import paths and driver versions are the two things codemods get right most of the time and wrong silently the rest.

Version jump

What changes

What to rehearse

2.x -> 3.x

Admin replatform to Next.js App Router

Custom routes, client/server boundaries, import paths

2.x -> 3.x

Config and adapter import changes

Run the codemod, verify the DB driver and connection config

3.x -> 4.x

Further codemod-driven config changes

Re-audit plugins and admin overrides; don't trust the codemod alone

Payload's database migration commands are available via npm run payload — create a migration for any schema difference the upgrade introduces and verify it on the staging copy.

Text
npm run payload migrate:create
npm run payload migrate

Plugins: Treat Each One as Its Own Migration

Assume no plugin is compatible until you've read its changelog for the version you're targeting. A plugin that peer-depends on the old admin internals will break the new admin whether or not the core upgrade is clean. For each plugin, check peer-dependency ranges, flag any admin component it injects, and test it in isolation. If you're assembling a plugin set for a Next.js project, we've written about the payload cms plugins we actually install and how to use payload cms with nextjs.

Cut Over With a Rollback Path, Not a Leap of Faith

When the dry run is clean, cut over with the previous release pinned as your fallback. The upgrade becomes a deploy, not a decision — and a deploy can be reverted. The shops doing this work treat the 3-to-4 move once stable lands as maintenance rather than a beta field trip. If you'd rather not own the dry run yourself, we run Payload migrations end to end.

That's the whole playbook for how to update payload cms without breaking the admin: rehearse it on a copy, verify every custom surface, and keep a way back.

FAQ

Should I update Payload CMS to v4 now or stay on v3?

Run the 3-to-4 migration once a stable release is out; betas are for testing the path, not for production workloads.

What breaks in the Payload admin during a major update?

The 3.0 admin replatformed from a React Router SPA onto the Next.js App Router, so custom views, field components, and routes often need rework.

Do I need a staging database to update Payload CMS safely?

Yes. Copy the production database to staging and rehearse the full upgrade there before you touch live data.

Will a codemod update my Payload config automatically?

Payload ships a codemod for major-version config changes, but you still verify adapters, plugins, and admin overrides by hand.

Written by
techpotions
All entries
The Redirect Map That Protects WordPress Rankings
The weekly

One email a week, from the workshop.

What we published, what we shipped, and the free packs as they land. No drip sequence, no webinar, unsubscribe in one click.