upgrade-packages-js_skill

Overview

This skill safely upgrades JavaScript and TypeScript project dependencies with breaking-change detection, migration guidance, and automated code migrations across npm, pnpm, and yarn. It enforces git safety by requiring a clean working tree and a new branch, detects package manager and monorepo layout, and runs stepwise upgrades to minimize risk. The skill produces actionable evidence for major upgrades and either applies codemods or prompts for manual migration steps.

How this skill works

It first verifies the repository is a JavaScript/TypeScript project and detects the package manager and lockfile to avoid mixing tools. It enforces a git safety gate (clean tree + new branch) and runs pre-upgrade checks: lockfile integrity, Node engine, ESM/CJS, peer deps, and stale package age. For each candidate upgrade it analyzes dependency trees, searches for breaking-change evidence (releases, changelogs, migration guides, codemods) and either applies automated codemods or returns a migration plan and tests to run. Majors are handled one at a time with time-boxing, tests, and mandatory documentation of skips.

When to use it

• You need to upgrade dependencies in a JS/TS (Node.js) project
• You want to minimize risk for major version upgrades with migration guidance
• You require git safety guarantees and reproducible lockfile commits
• You need automated codemods or concrete manual migration steps
• You maintain a monorepo and want workspace-aware upgrade sequencing

Best practices

• Always run the project language detection first and stop if not JS/TS
• Never mix package managers; enforce single detected PM and lockfile integrity
• Create a new branch before any install/upgrade and commit package.json + lockfile changes
• Upgrade incrementally: dev deps → patches → minors → majors (one major at a time)
• For major upgrades locate migration docs or perform an automatic web search before proceeding; if none found, ask the user
• Run build, typecheck, lint, and tests after each major upgrade and keep changes time-boxed

Example use cases

• Upgrade a single library (e.g., react 17→18) with migration guide and codemod application
• Bump multiple minor/patch dependencies across a workspace while preserving lockfile integrity
• Handle a framework upgrade (Next.js) with codemods, test updates, and paired package alignment
• Detect an incompatible peer dependency and propose an override or skip with documented rationale
• Audit old/stale packages (not updated >2 years) and either replace or flag them for manual review