Dependency Upgrades

/dependency-upgrade

Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. The user pastes their package.json, lockfile excerpt, npm outdated/npm audit output, or error messages; deliver an ordered upgrade plan, compatibility notes, codemod commands, and a rollback path as chat artifacts. For upgrading database schemas, use database-migration.

When to Use

• Upgrading major framework versions
• Updating security-vulnerable dependencies
• Modernizing legacy dependencies
• Resolving dependency conflicts
• Planning incremental upgrade paths
• Automating dependency updates

Semantic Versioning Review

MAJOR.MINOR.PATCH (e.g., 2.3.1)

MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

^2.3.1 = >=2.3.1 <3.0.0 (minor updates)
~2.3.1 = >=2.3.1 <2.4.0 (patch updates)
2.3.1 = exact version

Dependency Analysis

# npm
npm outdated
npm audit
npm audit fix

# yarn
yarn outdated
yarn audit

# Check for major updates
npx npm-check-updates
npx npm-check-updates -u  # Update package.json

# See why a package is installed
npm ls package-name
yarn why package-name

# Find duplicate packages
npm dedupe
yarn dedupe

Staged Upgrade Strategy

Phase 1: Planning

1. Identify current versions (npm list --depth=0).
2. Read CHANGELOG.md and MIGRATION.md for each major bump.
3. Order the upgrades: toolchain first (TypeScript, build tools), then the framework one major version at a time, then framework-adjacent libraries (router, testing libraries).

Phase 2: Incremental Updates

# Don't upgrade everything at once!

# Step 1: Update TypeScript
npm install typescript@latest
npm run test && npm run build

# Step 2: Update React (one major version at a time)
npm install react@17 react-dom@17
npm run test

# Step 3: Continue with other packages
npm install react-router-dom@6
# And so on...

Phase 3: Validation

• Unit tests pass before and after each step
• Integration tests cover the main user flows
• Visual regression snapshots for UI-affecting bumps
• E2E smoke test on the critical path
• Compatibility assertions (e.g., react and react-dom versions match, no peer dependency warnings in npm ls)

Breaking Change Handling

Codemods for Automated Fixes

# Run jscodeshift with a transform
npx jscodeshift -t <transform-url> src/

# Example: Rename unsafe lifecycle methods
npx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/

# For TypeScript files
npx jscodeshift -t <transform-url> --parser=tsx src/

# Dry run to preview changes
npx jscodeshift -t <transform-url> --dry src/

For changes without a published codemod, write a small migration script (glob the source tree, apply targeted regex or AST replacements) and deliver it as a chat artifact for the user to review before running.

Automated Dependency Updates

Renovate

// renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["major-update"]
    }
  ],
  "schedule": ["before 3am on Monday"]
}

Dependabot

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    reviewers:
      - "team-leads"
    commit-message:
      prefix: "chore"
      include: "scope"

Rollback Plan

Always upgrade on a branch. If tests fail after a bump: discard the branch and npm ci from the committed lockfile to restore the previous state. Commit the lockfile with each successful step so any single bump can be reverted independently.

Common Upgrade Patterns

# Lock file management
npm install --package-lock-only  # Update lock file only
npm ci                           # Clean install from lock file
yarn install --frozen-lockfile   # CI mode
yarn upgrade-interactive         # Interactive upgrades

# Peer dependency resolution
npm install --legacy-peer-deps   # Ignore peer deps (last resort)
npm install --force              # Override (understand what breaks first)

# Workspace upgrades
npm install --workspaces
npm install package@latest --workspace=packages/app

Usage

/dependency-upgrade $ARGUMENTS