upgrade-packages-js

Skill: Package Upgrade (Cross-Platform)

Safely upgrade JavaScript packages while minimizing breaking change risk, with migration guidance and automated code upgrades.

Non-Negotiables

1. Verify JavaScript project first - Stop immediately if not a JS/Node.js project
2. Never force upgrade all at once - Upgrade incrementally
3. Detect package manager first - npm/pnpm/yarn (including version)
4. Never mix package managers - Refuse if lockfiles conflict
5. Git safety gate first - Clean repo + new branch before upgrades
6. Breaking-change evidence check - For majors, check Releases/CHANGELOG/Migration/Codemods
7. For breaking upgrades: migrate code + tests - Apply codemods, implement fixes, add tests
8. Check peer dependencies - Ensure compatibility before upgrading
9. Check Node.js engine compatibility - Verify target versions support project's Node
10. Check ESM/CJS compatibility - Verify module system compatibility
11. Test after each major upgrade - Run build and tests
12. Keep lockfile updated - Commit lockfile changes
13. Document skipped packages - Record why packages were not upgraded
14. Time-box upgrades - Max time per major; if stuck, defer and document

Project Language Detection (MANDATORY - RUN FIRST)

This skill is for JavaScript/TypeScript (Node.js) projects only. Run this check before anything else.

node -e "
const fs=require('fs'),p=require('path'),cwd=process.cwd();
const checks=[
  ['package.json','javascript/typescript','This skill supports this project type'],
  ['go.mod','go','Use: go get -u ./... or go-mod-upgrade'],
  ['Cargo.toml','rust','Use: cargo update or cargo-upgrades'],
  ['requirements.txt','python','Use: pip-review --auto or pip-upgrader'],
  ['pyproject.toml','python','Use: poetry update or pdm update'],
  ['Pipfile','python','Use: pipenv update'],
  ['composer.json','php','Use: composer update'],
  ['Gemfile','ruby','Use: bundle update'],
  ['pubspec.yaml','dart','Use: dart pub upgrade'],
  ['pom.xml','java','Use: mvn versions:use-latest-releases'],
  ['build.gradle','java','Use: gradle dependencyUpdates'],
  ['*.csproj','dotnet','Use: dotnet outdated or nukeeper'],
  ['Package.swift','swift','Use: swift package update'],
  ['mix.exs','elixir','Use: mix deps.update --all'],
];
const found=checks.filter(([f])=>f.includes('*')?require('fs').readdirSync(cwd).some(x=>x.endsWith(f.slice(1))):fs.existsSync(p.join(cwd,f)));
if(found.length===0){console.error('ERROR: No recognized project files found');process.exit(1)}
const js=found.find(([_,l])=>l==='javascript/typescript');
if(js){console.log('OK: JavaScript/TypeScript project detected (package.json found)');process.exit(0)}
const other=found[0];
console.error('ERROR: This skill is for JavaScript/TypeScript (Node.js) projects only.');
console.error('Detected: '+other[0]+' ('+other[1]+' project)');
console.error('Suggestion: '+other[2]);
process.exit(2);
"