Playbooks · Coding agents

Migrate a small codebase to a new framework version with an agent

A solo builder moves a small Next.js app to a new major version: the official codemod does the mechanical work, an agent finishes the rest, and the build is the gate.

Audience: Solo builder · Stack: A small Next.js App Router app in a git repo, with a production build command · Tool: Next.js codemods, plus your coding agent for the remaining migration work

Before you start

• A small app — a handful of routes, not dozens — on a clean branch with a committed lockfile, so you can compare before and after and roll back by switching branches.
• A production build that passes before you start. Run your build command and record that it passes; a migration that starts red cannot be judged.
• The official upgrade docs for your target version open in front of you. This playbook uses the codemod commands from the official Next.js codemods docs, not a remembered upgrade recipe.
• A note of the app's key behaviours to check by hand afterwards: the pages and actions a user actually uses. A green build does not prove those still work.

Steps

1. On the migration branch, run the official upgrade codemod for a major version: npx @next/codemod upgrade major. The official docs describe this as upgrading your app while automatically running codemods and updating Next.js, React, and React DOM. Read its output and the resulting diff before going further.
2. Run the codemods for the specific breaking changes your app uses, one at a time, checking each diff. From the official docs: npx @next/codemod@latest middleware-to-proxy . renames the deprecated middleware convention to proxy, and npx @next/codemod@latest next-async-request-api . migrates dynamic APIs such as cookies(), headers(), and draftMode() to their asynchronous forms.
3. Search the diff for the codemod's own markers. The official docs say that where automatic migration is not possible, the codemod adds an @next-codemod-error comment and may add a temporary cast, and that you must complete the migration before removing them. Give those markers to your agent as its task list, one file at a time.
4. If you want a coding agent to run the codemods, complete the remaining work, and verify the app, the official docs give this command instead: npx next@canary upgrade --agent=latest. Note the canary tag in the docs' own command: this is a canary path, so keep the branch disposable and the diff reviewed.
5. After each round of agent changes, run the production build yourself and fix failures in small batches. Do not let the agent run ahead through several failures at once — each failure's cause gets harder to find.
6. When the build passes, walk your key behaviours by hand: load each main page, submit the main form, follow the main action. Compare against the pre-migration app, not against your memory of it.
7. Only then merge. Keep the old branch until the migrated app has run in production long enough for you to be confident, so a rollback is a branch switch, not a rescue.

Worked example

A solo builder has a small Next.js App Router site with three pages and a middleware.ts file that checks a login cookie. On a branch, they run npx @next/codemod upgrade major, then npx @next/codemod@latest middleware-to-proxy ., which renames the file to proxy.ts and the export to proxy, and npx @next/codemod@latest next-async-request-api . for a page that read cookies synchronously. The diff shows one @next-codemod-error marker where the cookie read could not be migrated automatically; the builder gives that single file to the agent, checks the fix, runs the build, then logs in and out by hand before merging. The mechanical renames took minutes; the one manual fix was the whole migration, and it was visible because the codemod marked it.

What can go wrong

• The build passes but a page behaves differently. Fix: this is the expected failure shape for a migration. Walk your key behaviours by hand; the build checks syntax and types, not behaviour.
• A codemod reports changes but the diff looks empty or tiny. Fix: check the file count. The official docs warn that a wrong path can report success with no files changed, so confirm the intended files actually changed.
• The agent “finishes” the migration by deleting code it did not understand. Fix: read the diff. Deletions of app code during a migration are the first thing to question.
• You upgraded two major versions at once and cannot tell which change broke what. Fix: stop, and redo it one major version at a time on separate branches. The official upgrade command accepts a revision, so a single step is a choice, not a requirement.

Limits

• Codemods apply mechanical transformations. They do not decide whether a new API fits your app, and a green build does not mean identical behaviour.
• The canary agent-upgrade command is a canary path by its own tag. Treat anything it produces as unreviewed until you have read the diff and run the build and the hand checks.
• This playbook covers a small app. A large app has more breaking changes, more markers, and more hand checks, and the same steps take proportionally longer — that time is NOT_MEASURED here.

Time and cost: NOT_MEASURED. This page gives no time or cost figure because the tool docs fetched for it state none that applies to this task.

Verification

Checked 2026-10-23 against the author's own docs. The workflow on this page was not run end to end; every command, flag, and capability claim was checked against an author doc or repo fetched that day.

• https://nextjs.org/docs/app/building-your-application/upgrading/codemods

Cut from this page, with reason:

• No Node.js version requirement stated: the fetched official codemods page does not state one in the sections used, so none is claimed here.
• No claim about which Next.js version to target beyond the major revision in the official command; the reader picks the target from the official upgrade guide.
• No time or cost figure: NOT_MEASURED.

If a step here does not match what your installed tool shows, trust the tool's own docs for your version and stop before approving a change you cannot read.

Back to: Coding playbooks hub · Skills index