# Upgrade Payload CMS to the Latest Version

Yes. An agent moves payload and every @payloadcms package to one new version, regenerates types and the import map, lints, type-checks and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/upgrade-payload/payload/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how Payload is pinned before it changes a number. In an app like payloadcms/website, `package.json` holds `payload` and eleven `@payloadcms/*` packages, the database adapter, the Next.js integration, the admin UI, live preview, the editor, storage, email and four plugins, all at the same exact version with no caret. They have to move as one: `@payloadcms/next` declares the matching `payload` version as a peer dependency. Two other things look like part of the set and are not. `@payloadcms/eslint-config` and its plugin sit at their own version in `devDependencies`. And the pnpm workspace has two packages under `preview-runtimes/`, one pinned to an older 3.x and one to a 4.0 canary, each on purpose.

It takes a baseline, since there are no tests to lean on. With pnpm at the version in `packageManager` and the Node major from `mise.toml`, it installs and runs `pnpm lint` and `pnpm exec tsc`, keeping the output, and saves copies of the two generated files: `src/payload-types.ts` and the admin import map. Then it reads the registry for the target: the newest version tagged `latest` on the current major, its `engines.node`, and the range of `next` that `@payloadcms/next` accepts. When this page was written, the latest 3.x release had dropped Node 18 and 20 and asked for a recent Node 22 or 24, while accepting the same Next.js ranges as the locked one. That kind of move is what the agent looks for.

The upgrade is one edit and three commands. It sets all twelve versions to the target, runs `pnpm install` so the lockfile follows, and reruns `pnpm generate:types` and `pnpm generate:importmap`. A diff in `payload-types.ts` after a version bump with no schema change means Payload's generated shapes moved, and the agent reads it against the release notes between the two versions. It reruns lint and the type-check and compares with the baseline, fixing type errors that the new version introduces in the repository's own code and listing any it cannot settle.

It is explicit about what it did not prove. `pnpm build` runs `payload migrate` and a Next.js build that reads content, so it needs MongoDB and the environment in `.env.example`. If the prompt asks for a boot check, the agent installs Docker in its sandbox, starts a MongoDB container, sets `DATABASE_URI` and a throwaway `PAYLOAD_SECRET`, starts the dev server and requests the admin route and one REST collection. Otherwise it stops at the static checks and says a preview deployment is the next gate. It leaves the two `preview-runtimes` packages, the ESLint packages and `next` itself alone unless the new peer range forces a change.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "codex",
  "input": "Upgrade Payload in this repository to the newest release tagged latest on the current major, and open a pull request. Read package.json, pnpm-workspace.yaml, the package.json files under preview-runtimes, mise.toml, tsconfig.json, .env.example, src/payload.config.ts, src/migrations and the workflows under .github first. List every dependency whose name is payload or starts with @payloadcms/, its current version, and whether it belongs to the core set that shares one version. Install pnpm at the version in packageManager and the Node major in mise.toml. Baseline on the untouched branch: pnpm install, pnpm lint, pnpm exec tsc, keeping the output, and copy src/payload-types.ts and the admin import map aside. From the registry read the target version, its engines.node and the peerDependencies of @payloadcms/next at that version; compare them with the Node version this repository pins and the installed next version, and report any conflict before going on. Set payload and every core @payloadcms package in the root package.json to the target, exactly, with no range. Do not change the packages under preview-runtimes, @payloadcms/eslint-config, @payloadcms/eslint-plugin, next or react. Run pnpm install, then pnpm generate:types and pnpm generate:importmap, and diff both generated files against the copies. Read the release notes between the two versions and tie each generated-file difference and each new lint or type error to a note. Fix errors in this repository's code that the upgrade causes; list any you cannot. Do not run pnpm build and do not start a database unless this prompt is extended to ask for it. If the repository is already on the target, end with one line saying so and open nothing. In the pull request give the versions before and after, the Node and Next.js requirements you read, the lint and type-check results on both sides, the generated-file diffs, and a short list of what to check on a preview deployment.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes the twelve version strings in `package.json`, `pnpm-lock.yaml`, and whichever of `src/payload-types.ts` and the import map the new version regenerates differently. If the upgrade made the repository's own code fail the type-check, those fixes are separate commits with the error each one answers. The description states the version before and after and the requirements read from the registry, so a Node floor that moved is the first thing a reviewer sees.

The evidence is a comparison. Lint and the type-check appear twice, on the baseline and after the upgrade, with new findings called out. Each change in a generated file is tied to a release note, or marked as unexplained when the agent could not find one. The description ends with what a preview deployment should confirm: the admin panel loads and saves a document, the Lexical editor's custom features render, live preview connects, and uploads reach the storage adapter. Those need a database and credentials the run does not have.

A reviewer checks that every core package shows the same version in the lockfile and no second copy of `payload` was installed, that the `preview-runtimes` packages still point at their own versions, and that no caret crept into `package.json`. Then look at the generated types diff. It is usually small, and it is the most direct statement of what the new version changed about your data's shape.

## Run it on every Monday morning

This repository already hears about each Payload release: its `on-payload-release` workflow receives a `repository_dispatch` for each release and syncs the documentation. Nothing bumps the dependency. To close that gap, add an automation in the Project that holds the repository with a `schedule` trigger, `cron` set to `0 9 * * 1` in your `timezone`, and this page's request as the prompt. The request ends with one line when there is no newer release, so a quiet week opens nothing. The automation has its own max runs per hour.

To react to each release instead of the calendar, give the automation a `webhook` trigger and call its URL from a step in your release workflow with `Authorization: Bearer` and the trigger's secret, plus an `Idempotency-Key` header on that trigger call set to the release tag, so a workflow re-run starts nothing new. The body you post becomes the event text after the prompt. A studio with many Payload sites sends this page's body per repository to `POST /o/{org}/sessions` with a `request_id` that is a UUID v5 of the repository's full name and the target version.

## Why run it on Rush?

Upgrading Payload means changing a dozen lines to the same string, which is why it is done carelessly: a find-and-replace, an install, a push, and the hope that the preview looks right. The parts that catch problems are skipped because each is a small chore. Was `engines` read? Did the generated types move? Is there one copy of `payload` in the lockfile or two? Did the type-check have these errors before? The agent does each chore every time, on a clean install with the pinned pnpm, and keeps both sides of every comparison.

It also keeps upgrades small. Three patch releases reviewed one at a time are three short diffs with short release notes; the same distance crossed in one jump is a longer read and a harder bisect when something breaks. A scheduled run in its own sandbox makes the small version the default, costs no developer time when there is nothing to do, and leaves a transcript of every command for the week something does change.

## Frequently asked questions

### Do all the @payloadcms packages really have to match?

The core ones do. `@payloadcms/next` lists the identical `payload` version as a peer dependency, and the adapters, editor and official plugins are released together with it. Mixed versions tend to install two copies of `payload`, which breaks type identity and context. Packages with their own release line, like the ESLint config, are left where they are.

### Will it upgrade Next.js at the same time?

Only if it must. The agent reads the `next` range that the target `@payloadcms/next` accepts and compares it with the installed version. If the installed version is inside the range, `next` is untouched. If it falls outside, the agent reports the conflict first and makes the smallest move that satisfies the range, as its own commit.

### Does it run database migrations?

No. The run has no access to your database and the request forbids starting one. `pnpm build` in this repository runs `payload migrate` at deploy time, so migrations are applied by your deployment. If the release notes mention a data change, the pull request says so and points at the note.

### Can it take us from Payload 3 to Payload 4?

That is a migration, not a weekly bump, and this request stays on the current major. Start it on purpose with a prompt that names the migration guide. The agent then works through config, collection and admin component changes on a long-lived branch, with the same baseline and generated-file comparisons.

### What if lint already fails before the upgrade?

Then the baseline shows it, and the pull request reports only what is new. The agent does not fix problems that were there before the upgrade unless the prompt asks, because mixing them into a dependency bump makes the diff impossible to review.

## More Payload CMS jobs

- [Write Unit Tests for a Payload CMS App](https://getrush.ai/run/write-unit-tests/payload/)
- [Review Pull Requests on a Payload CMS App](https://getrush.ai/run/review-pull-requests/payload/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade PHPUnit in a PHP Library Without Dropping Old PHP Versions](https://getrush.ai/run/upgrade-phpunit/php/)
- [Upgrade PHPUnit in a Slim 4 App](https://getrush.ai/run/upgrade-phpunit/slim/)
- [Upgrade Pinia 2 to Pinia 4 in a Vue 3 App](https://getrush.ai/run/upgrade-pinia/pinia/)
- [Upgrade Playwright and Its Browsers in a Test Suite](https://getrush.ai/run/upgrade-playwright/playwright/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
