Back to Explore
GuideVibeFix editorialUpdated Nov 20, 2026

Don't bet a major upgrade on one shot: an AI-assisted framework upgrade checklist

A major upgrade is not a version bump, it is old syntax expiring. This guide follows the React 19 and Next.js 16 official upgrade docs through the pre-upgrade baseline, breaking-change lists, codemods, the human-AI split of work, three layers of regression, and the first week after shipping, with a pre-ship checklist.

A developer typing on a laptop showing a dark code editor, with a phone lying on the white desk beside it

First, the boundaries. This site already has a guide on dependency upgrades and maintenance SOPs: how minor versions go up, how patches are applied, how lockfiles are managed. That one covers "routine work you do often." This guide covers something else: a one-off migration across a framework major version — React 18 to React 19, Next.js 15 to Next.js 16 — the kind that arrives with breaking changes. A routine upgrade can go slowly, and if something breaks you roll back one patch number; a major upgrade is a one-shot deal, and if you get it wrong the whole app may not run at all. There is also an API versioning and deprecation SOP, which covers how your own API retires old versions — that is "you asking others to upgrade"; this guide is "others asking you to upgrade," the opposite direction. Do not mix the two up.

The "Corner Shop" app used below is a fictional practice project: an ordering mini-app for a neighborhood grocery store, where you can place orders, check stock, and see the day's takings. Every action, command, and number built around it in this article was invented to explain the method. It is not a real record. All rules, commands, and changes for React 19 and Next.js 16 come from the two projects' official upgrade documentation; the sources are in each article's meta information and evidence record. Other frameworks have their own upgrade documentation. The thinking is the same, but the change lists differ, so check that framework's own upgrade guide before copying anything over.

Three things before the upgrade: don't start by editing the version number

The most common way a major upgrade dies is to edit the version number in package.json directly, install, run it, and fix whatever turns red. It sounds decisive; in practice it detonates every problem at once — compile errors, type errors, runtime errors, and test errors all mixed together, with no way to tell which ones the upgrade caused and which were already there. Before upgrading, do three things to shrink the blast radius.

First: upgrade to the transitional release. The React upgrade guide's first recommendation is exactly this: upgrade to React 18.3 first. That release is functionally identical to 18.2, with one difference: it prints a console warning for everything React 19 is going to remove — ReactDOM.render, defaultProps on function components, string refs, ReactDOMTestUtils.act — and warns whenever you use one. Clear those warnings first, then upgrade to 19, and the upgrade day has far fewer problems to face. A transitional release means "listen to the warnings first, then act" — do not skip this step. Other frameworks have the same idea: with Next.js, you clear deprecation warnings on the old version before crossing the major version.

Second: freeze feature work. Do not add new features during the upgrade. The upgrade branch does one thing only: the upgrade. A feature branch and the upgrade branch changing the same files at the same time produces merge conflicts that drive people mad. Agree with the team: while the upgrade branch lives, new features wait in line; a bug that must be fixed gets fixed on the main branch first and merged into the upgrade branch, never the other way around. The same applies to a one-person project: finish the feature in hand and commit it cleanly before opening the upgrade branch. The upgrade branch's commit history should stay clean: codemod commits, manual-change commits, and test-fix commits kept separate, not mashed into one unreadable commit.

Third: get the baseline green first. Before upgrading, the test suite, the type check, and the build should all be green — and write the results down. If the baseline is not green, then when things turn red after the upgrade you cannot tell whether the upgrade broke them or they were already broken. The baseline is "what the world looked like before the upgrade," and every judgment after the upgrade — "did this change break anything?" — is measured against it. For a project whose tests have never run at all, do not upgrade yet: first cover the few core flows (place an order, check stock, see the day's takings — three is enough), and only then talk about upgrading. Upgrading without a baseline is like defusing a bomb blindfolded.

How the 240 upgrade change points in the fictional Corner Shop project break down: 168 handled automatically by codemods, 52 handled by hand, 20 issues found in regression testing, 0 shipped with a known issue

Read the breaking-change list first: know what will break, then act

A major upgrade is not "install a new package" — it is "the old way of writing things has expired." Before acting, read the breaking-change list in the official upgrade documentation and know what will break. That list is your task list: every item on it maps to code you have to change. Take the lists in the React 19 and Next.js 16 official documents as examples.

What React 19 removes is all old syntax that had been warned about for years. First, ReactDOM.render and ReactDOM.hydrate are gone, replaced by createRoot and hydrateRoot. Both were deprecated since React 18, the official documentation's replacement is three lines, and a codemod can change them automatically — the lowest-risk item of all. Second, propTypes and defaultProps on function components are gone: propTypes checks are silently ignored — writing them is the same as not writing them — and defaultProps must become ES6 default parameters. Note the word "silently": it does not error, it just quietly stops working — the most dangerous kind of change, one tests may not even catch. Class components keep defaultProps, because classes have no ES6 default-parameter alternative. Third, string refs, findDOMNode, legacy Context (contextTypes and getChildContext), React.createFactory, and react-test-renderer/shallow are all removed, replaced respectively by callback refs, DOM refs, the new Context API, JSX, and installing the react-shallow-renderer package directly. Fourth, the test utility act moved from react-dom/test-utils into the react package, and the other test-utils functions were deleted outright. Fifth, errors thrown during render are no longer re-thrown: errors no error boundary catches go to window.reportError; errors a boundary catches go to console.error. If your production error reporting depends on errors being re-thrown, configure the two new hooks onUncaughtError and onCaughtError in createRoot.

The Next.js 16 list centers on three things. First, Turbopack is on by default: next dev and next build no longer need the --turbopack flag. If the project still has a custom webpack configuration, the build will fail outright to prevent misconfiguration — either migrate the webpack config to Turbopack options, or opt out explicitly with --webpack. Second, the runtime floor rises: Node.js 20.9 minimum, Node 18 no longer supported; TypeScript 5.1 minimum. Check the deployment environment's Node version before upgrading, not on deployment day when you discover the server still runs Node 18. Third, synchronous access to the async request APIs is fully removed: cookies(), headers(), draftMode(), plus params and searchParams, which still had a temporary synchronous compatibility period in Next.js 15, can only be accessed asynchronously in 16. The official documentation provides a dedicated codemod (next-async-request-api) and a type-generation tool (npx next typegen) for this part — do not hand-edit it; let the tools do it.

While reading the list, do one more thing: search your own codebase for every item on it. How many times does ReactDOM.render appear? How many defaultProps? How many synchronous cookies() calls? The counts you find are the size of this upgrade. Items with no hits get checked off and skipped; items with hits go onto the task list one by one. Only once the list is read and the work counted should you decide "do we upgrade this time, and when?" Upgrading without reading the list means not knowing what you are facing.

Codemods first: let the machine do the mechanical part

One word appears again and again in the official upgrade documentation: codemod — a script that reads your code, finds the old pattern, and rewrites it into the new one. The React 19 upgrade recipe is a single command: npx codemod@latest react/19/migration-recipe. It bundles five rewrites in one go: ReactDOM.render to createRoot, string refs to callback refs, the act import from react-dom/test-utils to react, useFormState renamed to useActionState, and propTypes converted to TypeScript types. The Next.js 16 upgrade codemod is npx @next/codemod@canary upgrade latest, which handles the Turbopack configuration location, migrating next lint to the ESLint CLI, the old middleware convention to proxy, and stripping the unstable_ prefix from stabilized APIs. The Next.js documentation also offers another route: upgrade with a coding agent (npx next@canary upgrade --agent=latest), letting the agent apply the changes step by step from the official migration guides and verify the app.

Before running a codemod, commit once. A codemod changes your files, and the working tree must be clean before it runs — a warning the official documentation and every tutorial share. After it runs, do not commit right away; read git diff first: which files did the codemod change, and is every change correct? Codemods are good at "simple, predictable rewrites," like turning ReactDOM.render into createRoot; they are bad at anything that needs a human decision. When reviewing the diff, focus on three kinds of places: is each change right (did it change anything it should not have?), is each change complete (did the same old pattern get changed in some files and missed in others?), and does the code still read sensibly after the change (some codemod output is awkward, and it is worth tidying by hand)?

Also remember what codemods cannot change. The React 19 upgrade guide states it directly: the silent failure of defaultProps is not covered by any codemod, and type-level changes need a separate run of npx types-react-codemod@latest preset-19 ./src. The Next.js 16 upgrade codemod is the same: it does not run every migration codemod, so if the project still uses synchronous params, searchParams, or cookies() from the Next.js 15 compatibility period, run the async request API codemod separately. A codemod is "a very fast first draft," not "the final answer." Use it as a first draft: let it change things first, then review, fill in, and finish by hand.

Take the most common case, ReactDOM.render, as an example. After the codemod, it should look like this — check the diff against this shape:

// Before: the old React 18 way
import { render } from 'react-dom';
render(<App />, document.getElementById('root'));

// After: the only way in React 19
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(<App />);

When reviewing, do not only check "did it change" — check "what is left in the entry file after the change": are the old imports fully removed? Is root reused by other code (for example, calling root.unmount() on teardown instead of the removed unmountComponentAtNode)? The entry file is where the whole app starts; get it wrong and not even the first screen renders. After a codemod touches the entry file, run the dev server by hand and watch the first screen appear with your own eyes before moving on.

What to let the AI do, and what not to: dividing the work in an upgrade

A framework upgrade is one of the best uses of AI, and also one of the easiest places for AI to lead you astray. If the division of work is unclear, the AI will produce an upgrade that looks fully changed and is full of holes. Write the division down and pin it to the upgrade branch description.

Let the AI do four things. First, mechanical rewrites: following the breaking-change list, batch-replace old syntax with new, including the corners the codemods do not cover. Second, generate the regression checklist: read the official upgrade documentation, list the "places that might be affected," and mark where each one sits in your own codebase. Third, explain errors: paste build errors and type errors one by one and ask it to explain "what this error means, and which item on the list it maps to." Fourth, write test patches: for the places that changed, add a few "old behavior vs new behavior" comparison tests.

Do not let the AI do three things. First, do not let it decide "whether to upgrade, or how far to upgrade this time." Upgrading to 19 or pinning at 18.3, migrating to Turbopack or holding on with --webpack — these are judgment calls that depend on the project: the AI does not know your deployment environment, your traffic, or your schedule. Second, do not let it quietly change behavior. When the AI rewrites code, it loves to "fix" things it finds awkward: an old API it does not recognize may simply be deleted rather than replaced per the list. When reviewing the diff, send back any change outside the list and ask what it was for. Third, do not let it make the ship decision for you. "The tests are all green, we can ship" is a sentence only a person can say. The AI does not know what real production traffic looks like, or how long a rollback takes.

One more iron rule: every change the AI makes must pass the baseline tests. Change one batch, run the tests, and only move to the next batch once they are green; if they turn red, stop and find out why before continuing. Do not wait until the AI has changed three hundred places before running the tests — by then a hundred failures will be red and you will not know which batch broke what. Small changes, small test runs: it sounds slow, and in an upgrade it is the fastest way to work.

Three layers of regression: types, tests, and walking the flows by hand

Once the upgrade changes are done, verification comes in three layers, and shipping with any layer missing is not allowed. Layer one is the type check: tsc --noEmit must be fully green. React 19's type changes are substantial: useRef no longer accepts being called with no argument, ref callbacks can no longer implicitly return a cleanup function, and @types/react must be upgraded to 19 in step. The type check is the cheapest layer — one run takes tens of seconds and catches a large share of the problems. Layer two is the test suite: run unit and integration tests in full and compare the results item by item against the pre-upgrade baseline. For each new failure, find out which it is: did the upgrade break it, or did the test itself hard-code the old behavior? Tests that hard-coded old behavior (for example, asserting that ReactDOM.render still exists) get updated to the new behavior; code the upgrade broke gets fixed. Layer three is walking the main flows by hand in the browser: place an order, check stock, see the day's takings. The things automation cannot catch — whether a page flickers, whether a button responds when tapped, whether a weak network makes it stall — only a person walking through once will find.

Beyond the three layers, one verification is easy to miss: the build output. Run a production build after the upgrade and check whether the bundle grew unexpectedly and whether new warnings appeared. With Turbopack now the default in Next.js 16, go through the warnings in the build log one by one: some say "your webpack configuration was ignored," others say "a plugin is not compatible with Turbopack." Build warnings are not decoration; every new warning during an upgrade is worth stopping to look at.

If the project has any way to roll out gradually, do not ship to everyone at once. Send it to a small slice of traffic first, watch the error logs for half a day, and only go to full traffic when no new errors appear. For a small project with no gradual rollout, at minimum be able to roll back: before shipping, keep the old deployment package, write down the rollback command, and confirm whether the database has any incompatible changes. A rollback plan is not something you prepare "because you think it will fail" — you prepare it "whether or not you think it will fail." On upgrade day, the most expensive thing is not the time spent fixing bugs; it is the time spent discovering something broke and not knowing how to get back.

The first week after the upgrade: watch three things

Shipping is not the end of the upgrade. Many upgrade problems do not appear the moment you ship; they surface slowly over the following week: a rarely used page opened for the first time, a scheduled job running for the first time, a user trying a cold feature for the first time. For the first week after the upgrade, watch three things.

The first is the error log. Compare the error volume of the week before the upgrade with the week after: which new errors appeared, and how many times a day does each occur? Focus on two kinds: errors caused by the changes on the upgrade list (for example, after the render-error reporting change, whether new error types you have never seen before show up in the log), and errors caused by "silent failures" (a feature quietly stops working, the user gets no error — it just cannot be used — and this kind of failure never appears in the log, so you need the second thing to find it). If the error volume is higher than before the upgrade, do not close the upgrade branch yet; keep it around, it makes fixes easier.

The second is user feedback. In the first week after the upgrade, ask the most active users directly: is anything behaving oddly, is any button unresponsive, is any page slower than before? User feedback is the only way to find a "silent failure": the code does not error, the tests are all green, but the feature is simply wrong — only the people using it know. When feedback arrives, do not rush to fix it; first confirm "was this caused by the upgrade, or was it always like this?" — compare against the pre-upgrade version, using the baseline described above.

The third is performance numbers. First-screen time, bundle size, API latency: compare all three against before the upgrade. Turbopack is now the default in Next.js 16, so builds are faster, but runtime behavior has to be measured, not assumed; new React 19 features need checking too, to confirm they did not bring along re-renders that should not happen. If performance got worse, do not rush to optimize; first confirm whether the upgrade caused it: roll back to the old version, measure once, and the comparison makes the cause clear. The week after the upgrade is the final step of the upgrade: once logs, feedback, and performance are all steady, the upgrade is truly done.

Five anti-patterns

Anti-pattern one: skipping major versions. React 16 straight to 19, Next.js 13 straight to 16, skipping every transitional release and warning period in between. The official upgrade documentation recommends one major version at a time: upgrade to 18 first, fix it, confirm it runs, then go to 19. The time skipping saves will be paid back double in debugging.

Anti-pattern two: sneaking features into the upgrade branch. The upgrade branch does only the upgrade; feature branches wait in line. Mix the two in one branch and, when something breaks, you cannot tell whose fault it is — and rolling back takes the feature down with it.

Anti-pattern three: running the codemod and never reviewing the diff. A codemod is a first draft, not the final answer. Committing without reviewing the diff means treating the machine's changes as your own. When reviewing, focus on: is each change right, is each change complete, and are there changes outside the list?

Anti-pattern four: ignoring silent failures. defaultProps on function components is silently ignored and does not error; the re-throwing of render errors changed and does not error either. These "changes that do not error" are the most dangerous. When reading the list, mark every place the word "silently" appears, and search for each one in the codebase and verify it in tests.

Anti-pattern five: upgrading without a baseline. The tests were already red, the types already failed, and after the upgrade they are redder — with no way to tell whose fault it is. Get the baseline green first, write it down, and only then open the upgrade branch. The baseline is the only reference point you have during the upgrade.

Checklist: run through it before shipping

Before you start: did you upgrade to the transitional release (are the React 18.3 warnings cleared)? Did you read the breaking-change list and search the codebase for how many hits each item has? Is feature work frozen and the upgrade branch clean? Are the three baseline checks (tests, types, build) all green, with the results written down? Is the deployment environment's Node version high enough (Next.js 16 needs 20.9 or above)?

While working: only run the codemod with a clean working tree; review the git diff before committing; list separately the things the codemod cannot do (types, defaultProps, async request APIs) and change them by hand; take the AI's changes one batch at a time — change a batch, run the tests, move on only when green; send back any change outside the list.

Before shipping: is the type check fully green? Is the test suite fully green and compared item by item against the baseline? Have the three main flows been walked by hand? Has a production build run, with every warning read? Is the rollback plan written down (the old deployment package, the rollback command, confirmation that the database is compatible)? Roll out gradually where possible; where not possible, at least make sure you can roll back. Pass all six, then ship. With upgrades, slow is fast: one well-prepared upgrade is faster than a "fast upgrade" redone three times.

Views 1Comments 0

Comments (0)

ME
0/1000
Loading comments...

Sources

Browse projectsPublish your project

Related articles

Real photo: a woman in an office sticking colorful sticky notes in rows on a white wall, holding a pink note in her hand
Guide
Stop shimming with margins: Flexbox one-dimensional layout, explained plainly

Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.

Developer WorkflowFrontend EngineeringAI Coding
Real photo: top-down view of hands sorting handwritten index cards on a dark desk, with clipboards holding tables beside them
Guide
Put the data in a labeled box first: objects and JSON, explained plainly

One order is one object: table, dishes, total, paid — all filed by label. This guide follows MDN's Working with objects, JSON, and Object references: object literals, dot vs bracket notation, adding and deleting properties, for...in with hasOwn, methods and this, getters and setters, references vs copies, Object.assign and friends, null-prototype objects, JSON's strict rules, and stringify and parse with their number-precision trap.

Developer WorkflowFrontend EngineeringAI Coding
Screenshot of Amp's new thread composer: the run-location picker lists Boxes, and the acme/workbench workspace shows the bug-tracker, tiny-crm, team-wiki and incident-database apps
News
An $18-a-Month Home for Agent-Built Software: Amp's Boxes Fill In the Last Missing Piece

On 10 November 2026, Amp launched Boxes: always-on mini-computers from $18 a month for deploying software you built with an agent. Each box runs its own runner, so the agent can edit live production data right there; the same month Amp also shipped Spaces, retired the Dial, and arrived on Windows — the agent's workplace is moving off the laptop into the cloud.

Developer WorkflowProduct LaunchDeployment