Upgrade packages

Safe, incremental dependency upgrades for pnpm projects. Pair with fix-dependency-security for audit and install hardening.

Principles

1. Prefer non-breaking upgrades — stay within semver ranges in package.json (^, ~) before jumping majors.
2. One logical change per commit — e.g. “bump patch/minors” vs “Next 15 → 16 + codemods”.
3. Framework libs are worth major upgrades — next, react, react-dom, typescript, tailwindcss, and the active linter (@biomejs/biome or eslint) — but require changelog review, codemods, and code fixes; never bump only the version pin.
4. Keep related packages aligned — React + types + DOM; Next + @next/env override; linter + its plugins (Biome or ESLint ecosystem).
5. Install with SFW when supply-chain hardening is enabled: sfw pnpm install / sfw pnpm update.

Upgrade tiers

Tier C “hard deps” (treat as framework): next, react, react-dom, typescript, tailwindcss, @biomejs/biome or eslint, @playwright/test, and UI stacks tightly coupled to React (motion, react-pdf, @react-pdf/renderer).

Tier A/B examples: clsx, lucide-react, class-variance-authority, @radix-ui/*, postcss, autoprefixer — upgrade freely after quick smoke check.

Workflow checklist

- [ ] 1. Baseline: pnpm outdated [-r]
- [ ] 2. Classify each outdated pkg (tier A / B / C)
- [ ] 3. Tier A/B: bump + sfw pnpm install
- [ ] 4. Tier C: read upgrade guide + run codemods
- [ ] 5. Fix types, lint, runtime breakages in app code
- [ ] 6. Align pnpm-workspace.yaml overrides (e.g. @next/env); fix trust downgrades via why/bump/override
- [ ] 7. pnpm audit, type-check, lint, build, e2e if relevant

Step 1: Discover what is outdated

pnpm outdated
pnpm outdated -r          # include transitive (plan overrides if needed)

Note current → wanted → latest and whether latest is a major bump.

pnpm why <package>        # if a transitive blocks resolution

Step 2: Tier A — safe in-range updates

Update everything that stays within existing semver ranges:

sfw pnpm update

Or target packages:

sfw pnpm update lucide-react clsx tailwind-merge

Re-run pnpm outdated. If wanted equals latest for a package, Tier A is done for it.

Step 3: Tier B — bump ranges without framework majors

Edit package.json to the new minor (or patch) range, then:

sfw pnpm install

Prefer one ecosystem group per PR (e.g. all Radix, or all dev tooling except ESLint).

Step 4: Tier C — framework major upgrades

4.1 Before bumping

1. Read the official upgrade / migration doc for the target major.
2. Check peer dependency requirements (e.g. Next 16 + React 19).
3. Search the repo for deprecated APIs (grep / semantic search).
4. Note codemods listed below; run them after installing the new version unless the doc says otherwise.

4.2 Bump versions together

Example — keep React family in sync:

"next": "<target>",
"react": "^19.x",
"react-dom": "^19.x"

"@types/react": "^19.x",
"@types/react-dom": "^19.x"

Update matching pnpm overrides in pnpm-workspace.yaml when the project pins ecosystem packages (e.g. @next/env with next).

sfw pnpm install

Respect minimumReleaseAge — very new majors may not install until policy allows; do not disable policy without user approval.

4.3 Codemods and migration tools

Run from repo root. Prefer official codemods first; then community.

Community / general:

• npx codemod@latest — catalog of recipes (codemod.com)
• npx npm-check-updates -u — only to propose version bumps; review diff carefully, do not blind commit

Always read codemod output and review the git diff — codemods are incomplete.

4.4 Manual follow-up

• Fix remaining tsc and linter errors (pnpm lint — Biome or ESLint per project).
• Update next.config.*, postcss.config.*, and linter config (biome.json or eslint.config.*) per migration guides.
• Run pnpm build and critical e2e paths (pnpm test:e2e).

Step 5: Trust downgrades (ERR_PNPM_TRUST_DOWNGRADE)

With trustPolicy: no-downgrade (see fix-dependency-security), installs can fail on a specific version.

1. Note the blocked package from the error.
2. Run pnpm why <package> — identify direct vs transitive path.
3. Resolve without trustPolicyExclude:

4. If the lockfile still lists the bad version after changing overrides, regenerate:

rm -rf node_modules pnpm-lock.yaml
sfw pnpm install --no-frozen-lockfile

5. Confirm with pnpm why <package> and pnpm install (lockfile policy check passes).

Step 6: Transitive / override conflicts

If pnpm install resolves but runtime or lint breaks (e.g. incompatible semver major after a trust override):

1. pnpm why <package>
2. Prefer removing or narrowing overrides over adding more pins.
3. Re-run Tier A update for the conflicting subtree.

Do not stack overrides to silence breakage without understanding the semver mismatch.

Step 7: Validate

pnpm audit
pnpm type-check
pnpm lint
pnpm build
pnpm test:e2e          # when UI/routing/auth changed

Report to the user:

• What was upgraded (tier A/B/C)
• Codemods run and manual edits made
• Outdated packages intentionally deferred (and why)
• Any policy blocks (minimumReleaseAge, trustPolicy)

Project-specific notes

See examples/README.md for battle-tested upgrade notes (e.g. Next.js portfolio / devprofile overlay).

Anti-patterns

• Jumping to latest on all packages in one commit
• Bumping next or react without running codemods or reading the migration guide
• Upgrading @types/react without react / react-dom
• Using pnpm update --latest on the whole tree without tier review
• Leaving pnpm outdated zero while audit or build is red
• Disabling minimumReleaseAge / trustPolicy to force a bleeding-edge major
• trustPolicyExclude instead of pnpm why + bump or overrides

Related skills

• audit-allow-builds — post-upgrade review of lifecycle-script packages in allowBuilds
• audit-ide-dependencies — editor extensions/plugins (not the project lockfile)
• fix-dependency-security — audit, SFW, workspace supply-chain policy

Related skills

• fix-dependency-security — audit, SFW, trustPolicy, override patterns for trust downgrades

References

• pnpm update
• pnpm why
• pnpm outdated
• Next.js codemods
• React 19 upgrade guide