Automate Dependency Upgrades and Ensure Compatibility

Dependency Upgrade guides major-version migrations, security updates, legacy modernization, dependency-conflict resolution, and incremental upgrade planning. It combines current-version inspection, release-note review, compatibility analysis, staged changes, and validation so a framework update is treated as a sequence of explicit decisions rather than a single bulk installation.

Semantic versioning provides an initial vocabulary for breaking changes, compatible features, and patches, but the skill does not treat version numbers as compatibility proof. Caret behavior below 1.0 needs special attention. Exact targets should come from release notes and peer requirements rather than an unqualified latest version. A compatibility matrix can organize relationships between a framework, its runtime companion, routing packages, and testing tools; the sample React matrix illustrates that structure rather than guaranteeing compatibility for a current project.

Use it when moving between major framework versions, remediating vulnerable packages, planning a modernization, or making dependency updates more systematic. It supports one-major-version-at-a-time changes with checks after each stage. Unrelated implementation work falls outside its scope, and environment-specific validation remains necessary.

Several referenced guides, checklist assets, a CSV matrix, and audit-dependencies.sh are not bundled in this catalog copy. Their dependent steps require an existing installation or original supporting material, reviewed contents, licenses, and execution prerequisites. There is no verified download source in the catalog. Fully documented inline steps can proceed independently, but missing scripts must not be fabricated or replaced by similarly named unrelated files.

Inputs include the current manifest and lockfile, installed dependency tree, desired exact versions, peer requirements, changelogs, migration notes, and a preserved starting state. An inspection example is:

npm list --depth=0

The workflow produces an upgrade order, compatibility notes, staged manifest and lockfile changes, migration edits, and validation evidence. It checks outdated and vulnerable dependencies, explains why packages are installed, and considers duplicate dependencies and workspace-specific updates. Existing UPGRADE_PLAN.md content must be preserved rather than overwritten by a sample command.

Inspection and mutation are separate. Audit fixes, deduplication, and npm-check-updates update modes change dependency state. CLI tools and codemods need pinned, reviewed versions and verified command syntax; illustrative parser and migration commands are not assumed runnable. Regex replacements can corrupt comments, strings, and imports, so reviewed AST transforms and inspection of every diff are preferred. Force and legacy-peer-deps switches bypass protections instead of resolving incompatibility.

Supported upgrade contexts include npm and Yarn, React and React DOM, TypeScript, routing libraries, testing libraries, and workspace packages. Lockfile-based installation supports reproducibility. Renovate and Dependabot examples organize scheduled updates and review, with automerge disabled rather than implicitly authorized.

Validation spans a pre-change baseline, unit and integration behavior, user flows, runtime checks, bundle size, performance, staging, and monitored rollout. Matching React versions or a DOM snapshot alone does not establish full runtime or visual correctness. Record the original full commit SHA and lockfile before changing dependencies. If validation fails, preserve the failed diff and logs, revert only task-owned changes when appropriate, and restore installation from the recorded lockfile without discarding other work.

The maintenance checklist also calls for updated upgrade notes and documentation. It warns against bulk updates, skipped major versions, ignored peer warnings, stale lockfiles, and proceeding without a rollback plan.