Skill v1.0.1
currentAutomated scan100/100+4 new
name: dependency-upgrade description: "Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches." risk: critical source: community date_added: "2026-02-27" metadata: version: "1.0.1"
Supporting material availability
This catalog copy contains the inline guidance below, but does not include the following supporting paths. They are external prerequisites, not bundled files:
<support-root>/references/semver.md<support-root>/references/compatibility-matrix.md<support-root>/references/staged-upgrades.md<support-root>/references/testing-strategy.md<support-root>/assets/upgrade-checklist.md<support-root>/assets/compatibility-matrix.csv<support-root>/scripts/audit-dependencies.sh
Ask for the original supporting material or an existing installation before using a step that depends on these paths; this catalog does not identify a verified download source for them. Resolve each path relative to that installation, inspect its contents, and verify any applicable license and execution prerequisites. Do not run a command or claim a referenced procedure was followed until its required file exists. Do not fabricate the missing scripts or treat an unrelated file with the same name as equivalent. Independent steps fully documented here can proceed within the user’s authorized scope; report any dependent step as unavailable.
Dependency Upgrade
Master major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing approaches.
Do not use this skill when
- The task is unrelated to dependency upgrade
- You need a different domain or tool outside this scope
Instructions
- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
Use this skill when
- 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
Separate inspection from mutation: npm audit fix/dedupe, yarn dedupe and ncu -u change dependency state. Pin and review codemods/CLI packages before running; the changelog-parser/react-codeshift command shapes below are illustrative and must be checked against the actual official tool, not assumed runnable. Regex migration is not syntax-aware and can corrupt strings/comments/imports; use reviewed AST transforms and inspect every diff. SemVer promises do not prove compatibility and caret rules differ below 1.0. Select exact targets from release notes/peer requirements instead of latest. --force/--legacy-peer-deps bypass protections rather than resolve incompatibility. A matching React version or DOM snapshot is not full runtime/visual verification. Do not overwrite an existing UPGRADE_PLAN.md or enable automerge implicitly.
Dependency Analysis
Audit Dependencies
# 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
# 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
// 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
# 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
# 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
// 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
# Use changelog parsersnpx changelog-parser react 16.0.0 17.0.0# Or manually checkcurl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md
Codemod for Automated Fixes
# React upgrade codemodsnpx react-codeshift <transform> <path># Example: Update lifecycle methodsnpx react-codeshift \--parser tsx \--transform react-codeshift/transforms/rename-unsafe-lifecycles.js \src/
Custom Migration Script
// 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 APIcontent = content.replace(/componentWillMount/g,'UNSAFE_componentWillMount');// Update importscontent = content.replace(/import { Component } from 'react'/g,"import React, { Component } from 'react'");fs.writeFileSync(file, content);});});
Testing Strategy
Unit Tests
// Ensure tests pass before and after upgradenpm run test// Update test utilities if needednpm install @testing-library/react@latest
Integration Tests
// 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
// visual-regression.test.jsdescribe('Visual Regression', () => {it('should match snapshot', () => {const { container } = render(<App />);expect(container.firstChild).toMatchSnapshot();});});
E2E Tests
// 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('user@example.com');cy.get('button[type="submit"]').click();cy.url().should('include', '/dashboard');});});
Automated Dependency Updates
Renovate Configuration
// renovate.json{"extends": ["config:base"],"packageRules": [{"matchUpdateTypes": ["minor", "patch"],"automerge": false},{"matchUpdateTypes": ["major"],"automerge": false,"labels": ["major-update"]}],"schedule": ["before 3am on Monday"],"timezone": "America/New_York"}
Dependabot Configuration
# .github/dependabot.ymlversion: 2updates:- package-ecosystem: "npm"directory: "/"schedule:interval: "weekly"open-pull-requests-limit: 5reviewers:- "team-leads"commit-message:prefix: "chore"include: "scope"
Rollback Plan
# Work on a topic branch with a clean or separately preserved starting state.# Record the original full commit SHA and lockfile before changing dependencies.# If validation fails, keep the failed diff and logs for diagnosis.# Review and revert only task-owned manifest/lockfile changes when appropriate,# then use npm ci to restore the recorded lockfile; never delete the branch or others' work.
Common Upgrade Patterns
Lock File Management
# 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
# npm 7+: strict peer dependenciesnpm install --legacy-peer-deps # Ignore peer deps# npm 8+: override peer dependenciesnpm install --force
Workspace Upgrades
# Update all workspace packagesnpm install --workspaces# Update specific workspacenpm install package@latest --workspace=packages/app
Resources
- references/semver.md: Semantic versioning guide
- references/compatibility-matrix.md: Common compatibility issues
- references/staged-upgrades.md: Incremental upgrade strategies
- references/testing-strategy.md: Comprehensive testing approaches
- assets/upgrade-checklist.md: Step-by-step checklist
- assets/compatibility-matrix.csv: Version compatibility table
- scripts/audit-dependencies.sh: Dependency audit script
Best Practices
- Read Changelogs: Understand what changed
- Upgrade Incrementally: One major version at a time
- Test Thoroughly: Unit, integration, E2E tests
- Check Peer Dependencies: Resolve conflicts early
- Use Lock Files: Ensure reproducible installs
- Automate Updates: Use Renovate or Dependabot
- Monitor: Watch for runtime errors post-upgrade
- Document: Keep upgrade notes
Upgrade Checklist
Pre-Upgrade:-[ ] Review current dependency versions-[ ] Read changelogs for breaking changes-[ ] Create feature branch-[ ] Backup current state (git tag)-[ ] Run full test suite (baseline)During Upgrade:-[ ] Upgrade one dependency at a time-[ ] Update peer dependencies-[ ] Fix TypeScript errors-[ ] Update tests if needed-[ ] Run test suite after each upgrade-[ ] Check bundle size impactPost-Upgrade:-[ ] Full regression testing-[ ] Performance testing-[ ] Update documentation-[ ] Deploy to staging-[ ] Monitor for errors-[ ] Deploy to production
Common Pitfalls
- Upgrading all dependencies at once
- Not testing after each upgrade
- Ignoring peer dependency warnings
- Forgetting to update lock file
- Not reading breaking change notes
- Skipping major versions
- Not having rollback plan
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.