Dependency Upgrade

by wshobson46891e7e60daNo licenseListed Oct 8, 2026Updated Oct 8, 2026

Manage major dependency version upgrades with compatibility analysis, staged rollout, and comprehensive testing. Use when upgrading framework versions, updating major dependencies, or managing breaking changes in libraries.

AI-generated overview

Guides major dependency version upgrades with compatibility analysis, staged rollout, testing, and rollback planning.

What it does
This skill provides instructions for planning and executing major dependency version upgrades. It covers semantic versioning review, dependency auditing and tree analysis, compatibility matrices, staged incremental upgrades, breaking-change handling with codemods, and testing strategies including unit, integration, visual regression, and E2E tests. It also documents automated update configuration for Renovate and Dependabot, lock file management, peer dependency resolution, workspace upgrades, and rollback procedures.
When to use it
Use it when upgrading major framework versions, updating security-vulnerable or legacy dependencies, resolving dependency conflicts, or planning incremental upgrade paths. It is also suited to setting up compatibility testing and automated dependency update workflows.
Requirements
No scripts are shipped; it is instructions only. Following the examples assumes a JavaScript/TypeScript project with npm or yarn, and optionally tools such as npm-check-updates, madge, jscodeshift, and test runners. Some examples reference network access to fetch changelogs or codemod transforms.

Dependency Upgrade

Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.

When to Use This Skill

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

Semantic Versioning Review

MAJOR.MINOR.PATCH (e.g., 2.3.1)
MAJOR: Breaking changesMINOR: New features, backward compatiblePATCH: 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

Audit Dependencies

bash
# npmnpm outdatednpm auditnpm audit fix
# yarnyarn outdatedyarn audit
# Check for major updatesnpx npm-check-updatesnpx npm-check-updates -u  # Update package.json

Analyze Dependency Tree

bash
# See why a package is installednpm ls package-nameyarn why package-name
# Find duplicate packagesnpm dedupeyarn dedupe
# Visualize dependenciesnpx madge --image graph.png src/

Compatibility Matrix

javascript
// compatibility-matrix.jsconst compatibilityMatrix = {  react: {    "16.x": {      "react-dom": "^16.0.0",      "react-router-dom": "^5.0.0",      "@testing-library/react": "^11.0.0",    },    "17.x": {      "react-dom": "^17.0.0",      "react-router-dom": "^5.0.0 || ^6.0.0",      "@testing-library/react": "^12.0.0",    },    "18.x": {      "react-dom": "^18.0.0",      "react-router-dom": "^6.0.0",      "@testing-library/react": "^13.0.0",    },  },};
function checkCompatibility(packages) {  // Validate package versions against matrix}

Staged Upgrade Strategy

Phase 1: Planning

bash
# 1. Identify current versionsnpm list --depth=0
# 2. Check for breaking changes# Read CHANGELOG.md and MIGRATION.md
# 3. Create upgrade planecho "Upgrade order:1. TypeScript2. React3. React Router4. Testing libraries5. Build tools" > UPGRADE_PLAN.md

Phase 2: Incremental Updates

bash
# Don't upgrade everything at once!
# Step 1: Update TypeScriptnpm install typescript@latest
# Testnpm run testnpm run build
# Step 2: Update React (one major version at a time)npm install react@17 react-dom@17
# Test againnpm run test
# Step 3: Continue with other packagesnpm install react-router-dom@6
# And so on...

Phase 3: Validation

javascript
// tests/compatibility.test.jsdescribe("Dependency Compatibility", () => {  it("should have compatible React versions", () => {    const reactVersion = require("react/package.json").version;    const reactDomVersion = require("react-dom/package.json").version;
    expect(reactVersion).toBe(reactDomVersion);  });
  it("should not have peer dependency warnings", () => {    // Run npm ls and check for warnings  });});

Breaking Change Handling

Identifying Breaking Changes

bash
# Check the changelog directlycurl https://raw.githubusercontent.com/facebook/react/master/CHANGELOG.md

Codemod for Automated Fixes

bash
# Run jscodeshift with transform URLnpx jscodeshift -t <transform-url> <path>
# Example: Rename unsafe lifecycle methodsnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js src/
# For TypeScript filesnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --parser=tsx src/
# Dry run to preview changesnpx jscodeshift -t https://raw.githubusercontent.com/reactjs/react-codemod/master/transforms/rename-unsafe-lifecycles.js --dry src/

Custom Migration Script

javascript
// migration-script.jsconst fs = require("fs");const glob = require("glob");
glob("src/**/*.tsx", (err, files) => {  files.forEach((file) => {    let content = fs.readFileSync(file, "utf8");
    // Replace old API with new API    content = content.replace(      /componentWillMount/g,      "UNSAFE_componentWillMount",    );
    // Update imports    content = content.replace(      /import { Component } from 'react'/g,      "import React, { Component } from 'react'",    );
    fs.writeFileSync(file, content);  });});

Testing Strategy

Unit Tests

javascript
// Ensure tests pass before and after upgradenpm run test
// Update test utilities if needednpm install @testing-library/react@latest

Integration Tests

javascript
// tests/integration/app.test.jsdescribe("App Integration", () => {  it("should render without crashing", () => {    render(<App />);  });
  it("should handle navigation", () => {    const { getByText } = render(<App />);    fireEvent.click(getByText("Navigate"));    expect(screen.getByText("New Page")).toBeInTheDocument();  });});

Visual Regression Tests

javascript
// visual-regression.test.jsdescribe("Visual Regression", () => {  it("should match snapshot", () => {    const { container } = render(<App />);    expect(container.firstChild).toMatchSnapshot();  });});

E2E Tests

javascript
// cypress/e2e/app.cy.jsdescribe("E2E Tests", () => {  it("should complete user flow", () => {    cy.visit("/");    cy.get('[data-testid="login"]').click();    cy.get('input[name="email"]').type("[email protected]");    cy.get('button[type="submit"]').click();    cy.url().should("include", "/dashboard");  });});

Automated Dependency Updates

Renovate Configuration

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

Dependabot Configuration

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

Rollback Plan

javascript
// rollback.sh#!/bin/bash
# Save current stategit stashgit checkout -b upgrade-branch
# Attempt upgradenpm install package@latest
# Run testsif npm run test; then  echo "Upgrade successful"  git add package.json package-lock.json  git commit -m "chore: upgrade package"else  echo "Upgrade failed, rolling back"  git checkout main  git branch -D upgrade-branch  npm install  # Restore from package-lock.jsonfi

Common Upgrade Patterns

Lock File Management

bash
# npmnpm install --package-lock-only  # Update lock file onlynpm ci  # Clean install from lock file
# yarnyarn install --frozen-lockfile  # CI modeyarn upgrade-interactive  # Interactive upgrades

Peer Dependency Resolution

bash
# npm 7+: strict peer dependenciesnpm install --legacy-peer-deps  # Ignore peer deps
# npm 8+: override peer dependenciesnpm install --force

Workspace Upgrades

bash
# Update all workspace packagesnpm install --workspaces
# Update specific workspacenpm install package@latest --workspace=packages/app

Source and attribution

Source:wshobson/agentsinplugins/framework-migration/skills/dependency-upgradeat commit46891e7

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal