Dependency Upgrades skill for Claude Code

An upgrade is done when the new versions are in the manifest and lockfile, every breaking change that touches this codebase has been handled on purpose, the full test suite and build pass, and the change is small enough to revert alone. Bumping versions and hoping CI catches the rest is not an upgrade process.

Ground rules

• One risk group per PR: patch/minor batch, or one major upgrade (with its tightly coupled companions, e.g. react + react-dom + @types/react). Never mix a major upgrade with feature work.
• Read the changelog or migration guide for every major version crossed, not just the target. Skipping from v3 to v6 means three sets of breaking changes.
• Commit the lockfile with the manifest. Never delete and regenerate the whole lockfile to fix one conflict; it silently upgrades hundreds of transitive packages.
• Use the project’s package manager and its pinned version (packageManager field, corepack, .tool-versions). Mixing managers corrupts lockfiles.
• Get a green baseline first. Upgrading on a red suite hides which failures are yours.

Workflow

- [ ] 1. Baseline: clean tree, green tests, record versions
- [ ] 2. Inventory what is outdated and why it matters
- [ ] 3. Group and order upgrades by risk
- [ ] 4. For each major: read changelog, run codemods, fix, test
- [ ] 5. Update lockfile minimally; dedupe; audit
- [ ] 6. Verify: tests, build, type check, runtime smoke test
- [ ] 7. PR with breaking changes handled and rollback note

1-2. Baseline and inventory

Ecosystem	Outdated	Why is X installed	Vulnerabilities
npm	npm outdated	npm explain <pkg>	npm audit
pnpm	pnpm outdated -r	pnpm why <pkg>	pnpm audit
Yarn (berry)	yarn upgrade-interactive	yarn why <pkg>	yarn npm audit
uv	uv tree --outdated	uv tree --invert --package <pkg>	uvx pip-audit
pip	pip list --outdated	pipdeptree -r -p <pkg> (if installed)	pip-audit
Poetry	poetry show --outdated	poetry show --tree	pip-audit on export
Go	go list -m -u all	go mod why -m <mod>	govulncheck ./...
Cargo	cargo outdated (plugin) or cargo update --dry-run	cargo tree -i <crate>	cargo audit (plugin)
Bundler	bundle outdated	bundle exec gem dependency <gem> --reverse-dependencies	bundle audit (plugin)

Prioritize: security fixes with a reachable code path > end-of-life runtimes and frameworks > blockers for other upgrades > deprecation warnings > everything else.

3. Group and order

1. Runtime/toolchain first if required (Node LTS, Python minor, Go version), since packages may require it.
2. Patch and minor updates of everything, as one batch, if tests are good. Bisect the batch if it breaks.
3. Majors one at a time, foundational first (framework before its plugins; TypeScript before typed libraries; test runner separately from app code).

4. Major upgrades

1. Read the migration guide and the changelog entries between current and target. Extract a checklist of breaking changes; grep the codebase for each affected API.

grep -rn "componentWillMount\|ReactDOM.render" src     # example: React 19 removals

2. Run the official codemod or upgrade tool where one exists:

Upgrade	Tool
Next.js	npx @next/codemod@latest upgrade
React 19	npx codemod@latest react/19/migration-recipe
Angular	npx ng update @angular/core @angular/cli
Tailwind CSS v4	npx @tailwindcss/upgrade
ESLint flat config	npx @eslint/migrate-config .eslintrc.json
Storybook	npx storybook@latest upgrade
Python syntax	ruff check --select UP --fix (pyupgrade rules)
Django	django-upgrade --target-version <x.y> on changed files
Go modules	go get <mod>@latest && go mod tidy; for v2+ the import path changes (/v2)

Commit codemod output separately from hand fixes so reviewers can skim it.

3. Upgrade the package:

npm install next@latest react@latest react-dom@latest
pnpm up next@latest --filter web            # one workspace package
pnpm up -r --latest "@types/*"              # pattern across workspace
uv lock --upgrade-package django && uv sync
poetry add django@^5.2
go get github.com/jackc/pgx/v5@latest && go mod tidy
cargo update -p serde                        # within semver range
bundle update --conservative rails           # keep shared deps at current versions

4. Fix remaining failures guided by the breaking-change checklist, type errors, and deprecation warnings in test output. Treat new deprecation warnings as work for this PR when cheap, or a ticket.

5. Lockfile hygiene

• Resolve lockfile merge conflicts by taking one side and re-running install, not by hand-editing.
• Dedupe after upgrades: npm dedupe, pnpm dedupe, yarn dedupe.
• Force a transitive version only as a documented stopgap: npm overrides, pnpm overrides (pnpm-workspace.yaml in pnpm 10, or pnpm.overrides in package.json), Yarn resolutions. Add a comment or issue link explaining when to remove it.
• Peer dependency conflicts: find which package lags (npm ls <peer>), upgrade it or wait; --legacy-peer-deps only with a written reason, never as a default.

6. Verify

• Full test suite, type check, lint, production build.
• Start the app and exercise the main flows; many breakages (SSR, bundling, env loading) only appear at runtime.
• Diff the lockfile scope: git diff --stat package-lock.json; an unexpectedly huge diff means you upgraded more than intended.
• For libraries you publish, check that the declared peer/engine ranges still match.
• Watch bundle size and startup time for frontend/CLI projects.

7. PR

## Upgrade Next.js 14.2 -> 15.5

**Breaking changes handled**
- Async request APIs: `cookies()`/`headers()` now awaited (codemod, 23 files)
- `fetch` no longer cached by default: added `cache: 'force-cache'` to 4 catalog fetches
**Not affected:** next/image changes (we use a custom loader).
**Codemod commit:** a1b2c3d (mechanical; skim). Hand fixes: e4f5g6h.
**Verification:** tests 512 pass; build OK; smoke-tested checkout and auth on preview.
**Rollback:** revert this PR; no data or config migrations.

Renovate and Dependabot triage

PR type	Policy
Patch/minor, dev dependency, green CI	Automerge (grouped)
Patch/minor, runtime dependency, green CI	Merge in a weekly batch after a quick changelog skim
Major	Treat as a planned upgrade (workflow above); never auto-merge
Security fix	Merge promptly; check if the vulnerable path is reachable to judge urgency
Red CI	Do not merge; open a ticket or fix in the bot branch

Configuration patterns:

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "minimumReleaseAge": "3 days",
  "packageRules": [
    { "matchUpdateTypes": ["minor", "patch"], "matchDepTypes": ["devDependencies"],
      "groupName": "dev dependencies (non-major)", "automerge": true },
    { "matchPackageNames": ["/^@types\//"], "groupName": "type definitions" },
    { "matchUpdateTypes": ["major"], "dependencyDashboardApproval": true }
  ]
}

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: "/"
    schedule: { interval: weekly }
    groups:
      minor-and-patch:
        update-types: ["minor", "patch"]

A release-age delay (Renovate minimumReleaseAge, Dependabot cooldown, pnpm minimumReleaseAge) protects against compromised or yanked releases; recommend a few days for runtime dependencies.

Gotchas

• npm update respects semver ranges and never crosses majors; npx npm-check-updates -u rewrites ranges to latest including majors. Know which one you ran.
• Caret ranges on 0.x packages (^0.4.1) allow only patch updates, while 0.x minors are often breaking anyway.
• Type-only packages (@types/*) can break builds without runtime changes; keep them aligned with the runtime package major.
• Go major versions are new module paths; go get -u ./... will not cross them.
• A green CI on a bot PR proves only what the tests cover. Runtime-only breakage (config schema, env var renames, SSR) needs a smoke test.
• Transitive upgrades from lockfile regeneration are the most common source of “nothing changed but it broke”.

Verification

• Manifest and lockfile changed together and only for the intended packages.
• Every breaking change in the migration guide is marked handled or not applicable.
• Tests, type check, build, and a manual smoke run pass; audit shows no new advisories.