Playbooks · Coding tasks
Upgrade dependencies one package at a time, with a rollback for each
Written October 27, 2026 · Edited November 11, 2026
For a solo builder × upgrading one dependency × Claude Code, ending with each package upgraded alone, tested against a baseline recorded before the upgrade, and rolled back on its own if the tests fail.
Before you start
This page is not the framework migration playbook. The migration playbook moves a small Next.js app to a new framework version with the official codemods, and the build is the gate. This page does not change a framework version and does not run a codemod. It upgrades individual packages in a project that stays on the same framework version, one package at a time, with the test suite as the gate for each package and a rollback that touches only that package.
You need a project that uses npm, a test command you already run, and a clean git state so the change for each package can be read on its own. Work on a branch, not on your main branch, so an upgrade that goes wrong can be set aside without disturbing working code. Before any upgrade, record two things: the output of npm outdated, which shows the current, wanted, and latest version of each package, and the result of your test command, exactly as it ran. A baseline recorded after the first upgrade is not a baseline. If the tests do not pass before you start, stop: an upgrade judged against a failing suite cannot be judged at all.
Read the version columns in the npm outdated output carefully, because they mean different things. In the npm docs, wanted is the highest version that satisfies the semver range in package.json, and latest is the version tagged as latest in the registry, which may sit above that range. A newer version above your range is usually a new major version, and the docs mark that case as one to proceed with cautiously. The steps below keep those two cases apart: an upgrade inside the range and a jump to the latest version are different commands, and the jump is the one that needs the closest reading of what changed.
What "done" looks like
At the end of one sitting you have a short, readable record: the baseline test result, one commit per package upgraded with the old and new version named in it, a test result after each upgrade compared with the baseline, and a list of the packages you deliberately left alone, with the reason for each. A package that failed its tests is back at its previous version, with its tests passing again, and nothing else was changed to get it there.
Steps
- Record the baseline before touching anything. Run
npm outdatedand save its output, and run your test command and save its result, including any failures. Note the current version of each package you plan to upgrade, because the rollback in step 6 needs that exact version. Do not let the agent run these commands for you and report back a summary; run them yourself and keep the output where you can compare against it later. - Pick one package, and only one. Start with a package whose wanted version is newer than its current version, so the upgrade stays inside the semver range already in
package.json. Leave packages whose only newer version is the latest version, above the range, until the inside-the-range upgrades are done and committed. A group of packages counts as one step only if you can state in one sentence why they must move together; otherwise each package is its own step. - Ask Claude Code to propose the upgrade before it makes any change. In plan mode, Claude Code reads files and proposes a plan but makes no edits until you approve it. Ask for the exact command it would run, the version it expects to install, the changes it found in the package's own release notes, and the files it expects to change. Read the plan yourself. If the plan names more than the one package, or edits code beyond what the upgrade requires, narrow it before approving anything.
- Upgrade that package alone, with the command that matches the case. For an upgrade inside the semver range, run
npm update <pkg> --save, naming the one package. The npm docs say thatnpm updatewith no package name updates all packages, and that by default it does not update the semver values inpackage.json; the--saveflag is what also updates the values inpackage.json. Do not run a barenpm update. For a jump to the latest version, above the range, runnpm install <pkg>@latestinstead: the npm docs describe installing a package at a tag, with the default tag being latest. Read the output and check that only the named package moved. - Read the diff, then run the tests and compare with the baseline. Open the diff yourself. The
package.jsonchange should name only the one package. If the diff shows edits to your own code that you did not approve, stop and ask Claude Code to explain each one before going further. Then run your test command and compare the result with the baseline from step 1, line by line. A new failure belongs to this package until proven otherwise, because this package is the only thing that changed. - If the tests pass, commit that package alone. If they fail, roll back that package alone. A passing upgrade gets its own commit naming the package and the old and new versions, so the history shows one decision per commit. A failing upgrade is rolled back by reinstalling the recorded previous version:
npm install <pkg>@<previous-version>. The npm docs describe installing a specified version of a package in exactly this form, and say the install fails if that version has not been published. Before running the tests again, comparepackage.jsonand the lockfile against the pre-upgrade record withgit diffon the branch, and confirm both match the baseline. If either still shows the upgraded version, a changed range, or newer transitive entries, restore those files from the baseline and re-run the install before judging the rollback complete. After the rollback, run the tests again and confirm the result matches the baseline before moving on. Do not roll back by undoing every change on the branch, and do not fix the failure by editing your own code or your tests to suit the new version without recording that as a separate, deliberate decision. - Repeat from step 2 for the next package, only after the previous one is committed or rolled back. Never stack a second untested upgrade on top of a first. Each package gets its own plan, its own diff read, its own test comparison, and its own commit or rollback. When a package's upgrade needs a change to your own code, that change is reviewed as part of that package's step, not carried into the next one.
- Finish with a full check and an honest leftover list. Run the test command once more over the whole project, run
npm outdatedagain, and write down what is still outdated and why: a package left at its old version because its latest version is a major jump, a package whose upgrade failed and was rolled back, or a package you chose not to touch. That list is part of the result, not a loose end to hide.
Check the agent's work
- Check that the baseline test result was recorded before the first upgrade, and that each later result was compared with it rather than judged on its own.
- Check that each diff changes only the one package named in that step, in
package.jsonand the lockfile, plus any code change you explicitly approved. - Check that no step ran a bare
npm updatewith no package name, which updates all packages and destroys the one-at-a-time record. - Check that a jump to a latest version above the semver range was run as an install at a tag or version, not as an update, and that its release notes were read before it ran.
- Check that every rollback reinstalled the recorded previous version of that package only, and that the tests were re-run after the rollback.
- Check that each commit names one package and its old and new versions, so any single upgrade can be found and undone later.
What can go wrong
- Upgrading everything at once. A bare
npm updatemoves every package, and the first failing test then has a dozen possible causes. The fix is to stop, return to the baseline, and redo the work one package at a time. - Confusing wanted with latest. The wanted column stays inside the range in
package.json; the latest column may be a new major version. Treating them as the same thing turns a routine update into an unplanned major upgrade. Read both columns before choosing the command. - The agent fixing a failure by changing your tests. A test edited to pass under the new version is not evidence that the upgrade is safe. Read the diff: test changes belong in their own reviewed decision, never silently inside an upgrade step.
- Rolling back everything instead of one package. Undoing the whole branch to fix one bad upgrade also undoes the good upgrades. Reinstall the one package at its previous version and re-run the tests.
- Skipping the baseline because the suite "usually passes." A suite that usually passes may already be failing for an unrelated reason. Without a recorded baseline, that failure gets blamed on the upgrade, or the upgrade gets blamed for nothing, and neither conclusion can be checked.
Limits
- This page covers npm only. No pnpm or Yarn command appears here, because their upgrade documentation was not read for this page.
- Passing tests show that the tested behavior still works. They do not prove that untested behavior is unchanged, and this page promises no such proof.
- The commands here follow the npm CLI v10 documentation and the Claude Code common-workflows documentation. A different installed version may show different output; the docs for the version you have installed govern.
Related playbooks
- Check every package name your agent invents
- Dependabot now updates agent package managers
- OpenCode 1 offers the upgrade to OpenCode 2
- Codex is now an official Termux package
Sources
Sources: npm outdated, npm update, npm install, Claude Code common workflows.
Back to: Coding playbooks hub