Automate Dependency Upgrades and Ensure Compatibility

Dependency Upgrade is a skill for mastering major dependency version upgrades, compatibility analysis, staged upgrade strategies, and comprehensive testing. It opens with a semantic versioning primer covering caret and tilde range semantics:

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

It then documents dependency auditing (npm outdated/audit/audit fix, yarn outdated/audit, npx npm-check-updates), dependency-tree analysis (npm ls, yarn why, npm dedupe, npx madge for visualization), and a JavaScript compatibility-matrix pattern that maps a package's major versions to compatible peer-dependency ranges, illustrated for React 16.x/17.x/18.x against react-dom, react-router-dom, and @testing-library/react.

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, or automating dependency updates. It is not for tasks unrelated to dependency upgrades or for work in a different domain or tool outside this scope.

Given a dependency-upgrade task, the skill outputs a three-phase staged plan - Planning (identify current versions and read CHANGELOG/MIGRATION docs to build an ordered UPGRADE_PLAN.md), Incremental Updates (upgrade and test one package at a time rather than all at once), and Validation (compatibility tests asserting peer packages like react and react-dom share compatible versions) - breaking-change tooling (changelog-parser, codemods such as react-codeshift for renaming unsafe lifecycle methods, and custom migration scripts using regex-based find/replace across source files), a four-layer testing strategy (unit, integration, visual-regression snapshot, and Cypress E2E tests), automated-update configs for Renovate and Dependabot, and a rollback script that stashes changes, attempts the upgrade on a branch, and reverts to main if tests fail. Seven supporting reference and asset files back this up: references/semver.md, references/compatibility-matrix.md, references/staged-upgrades.md, references/testing-strategy.md, assets/upgrade-checklist.md, assets/compatibility-matrix.csv, and scripts/audit-dependencies.sh.

Works across npm and yarn tooling, including npm 7+/8+ peer-dependency flags --legacy-peer-deps and --force, and npm/yarn workspace-wide upgrade commands, plus Renovate and Dependabot for automated PR-based updates, and testing frameworks implied by the examples (unit/integration test runners, Testing Library, Cypress for E2E). Eight best practices are stated: read changelogs, upgrade incrementally one major version at a time, test thoroughly across unit/integration/E2E, check peer dependencies early, use lock files for reproducible installs, automate updates via Renovate/Dependabot, monitor for post-upgrade runtime errors, and document upgrade notes. Seven common pitfalls are named: upgrading everything at once, skipping post-upgrade testing, ignoring peer-dependency warnings, forgetting to update the lock file, skipping changelog review, skipping major versions, and having no rollback plan.

Engineers and teams planning or executing major dependency and framework upgrades who want a staged, tested, rollback-safe process - with a concrete pre/during/post-upgrade checklist - rather than bumping versions and hoping nothing breaks.