dependency-upgrade

Dependency Upgrade

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

Do not use this skill when

Instructions

Use this skill when

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

Audit Dependencies

# 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

Analyze Dependency Tree

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

npm dedupe
yarn dedupe
Visualize dependencies

npx madge --image graph.png src/

Compatibility Matrix

// compatibility-matrix.js
const 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 versions
npm list --depth=0
2. Check for breaking changes

Read CHANGELOG.md and MIGRATION.md
3. Create upgrade plan

echo "Upgrade order:
TypeScript

React

React Router

Testing libraries

Build tools" > UPGRADE_PLAN.md

Phase 2: Incremental Updates

# Don't upgrade everything at once!
Step 1: Update TypeScript

npm install typescript@latest
Test

npm run test
npm run build
Step 2: Update React (one major version at a time)

npm install react@17 react-dom@17
Test again

npm run test
Step 3: Continue with other packages

npm install react-router-dom@6
And so on...

Phase 3: Validation

// tests/compatibility.test.js
describe('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 parsers
npx changelog-parser react 16.0.0 17.0.0
Or manually check

curl https://raw.githubusercontent.com/facebook/react/main/CHANGELOG.md

Codemod for Automated Fixes

# React upgrade codemods
npx react-codeshift <transform> <path>
Example: Update lifecycle methods

npx react-codeshift \
  --parser tsx \
  --transform react-codeshift/transforms/rename-unsafe-lifecycles.js \
  src/

Custom Migration Script

// migration-script.js
const 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

// Ensure tests pass before and after upgrade
npm run test
// Update test utilities if needed
npm install @testing-library/react@latest

Integration Tests

// tests/integration/app.test.js
describe('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.js
describe('Visual Regression', () => {
  it('should match snapshot', () => {
    const { container } = render(<App />);
    expect(container.firstChild).toMatchSnapshot();
  });
});

E2E Tests

// cypress/e2e/app.cy.js
describe('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": true
    },
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "labels": ["major-update"]
    }
  ],
  "schedule": ["before 3am on Monday"],
  "timezone": "America/New_York"
}

Dependabot Configuration

# .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

// rollback.sh
#!/bin/bash
Save current state

git stash
git checkout -b upgrade-branch
Attempt upgrade

npm install package@latest
Run tests

if 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.json
fi

Common Upgrade Patterns

Lock File Management

# npm
npm install --package-lock-only  # Update lock file only
npm ci  # Clean install from lock file
yarn

yarn install --frozen-lockfile  # CI mode
yarn upgrade-interactive  # Interactive upgrades

Peer Dependency Resolution

# npm 7+: strict peer dependencies
npm install --legacy-peer-deps  # Ignore peer deps
npm 8+: override peer dependencies

npm install --force

Workspace Upgrades

# Update all workspace packages
npm install --workspaces
Update specific workspace

npm install package@latest --workspace=packages/app

Resources

Best Practices

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 impact
Post-Upgrade:
[ ] Full regression testing

[ ] Performance testing

[ ] Update documentation

[ ] Deploy to staging

[ ] Monitor for errors

[ ] Deploy to production

Common Pitfalls