Update NPM Dependencies

Upgrade npm dependencies intelligently, researching breaking changes for major version updates.

Optional filter: $ARGUMENTS (e.g., react , react axios lodash )

Phase 1: Monorepo Detection

Search for package.json files in the project (excluding node_modules ):

find . -name "package.json" -not -path "/node_modules/" -not -path "/.git/"

• If one found: proceed with that location

• If multiple found: use AskUserQuestion to let user choose which to update (multiSelect allowed)

• If none found: inform user and exit

Phase 2: Discovery

For each selected package.json location:

• Change to the directory containing package.json

• Run npm-check-updates to discover available updates:

ncu --format group

If a filter was provided via $ARGUMENTS :

ncu --format group --filter "$ARGUMENTS"

Parse the output to categorize updates:

• Major (breaking changes) - requires migration research

• Minor (new features, backward compatible)

• Patch (bug fixes)

Create TodoWrite tasks for each major update package

If no updates are available, inform the user and exit.

Phase 3: User Strategy Selection

Present a summary showing:

• Count and list of major updates (with current → target versions)

• Count of minor updates

• Count of patch updates

Use AskUserQuestion to ask upgrade strategy:

Header: "Strategy" Options:

• Cautious - Upgrade minor/patch first, then major one-by-one with research

• All at once - Research all major changes, then upgrade everything together

• Skip major - Only upgrade minor and patch versions

• Interactive - Ask for each major update individually

Phase 4: Research Breaking Changes

For each package with a major version update:

Step 1: Calculate Version Gap

Identify all major versions between current and target. For example:

• react: 17.0.2 → 19.0.0 → research v18 AND v19 breaking changes

• jest: 27.5.1 → 29.7.0 → research v28 AND v29 breaking changes

Step 2: Research Each Major Version

For each major version in the gap, search for migration documentation:

WebSearch: "[package-name] v[X] migration guide" WebSearch: "[package-name] v[X] breaking changes"

Common sources:

• GitHub releases: https://github.com/[org]/[repo]/releases

• Official docs migration guides

• Changelog files

Step 3: Extract Key Breaking Changes

From the migration docs, identify:

• API changes (renamed/removed functions)

• Configuration changes

• Peer dependency requirements

• Behavioral changes

• Deprecated features now removed

Step 4: Search Codebase for Affected Code

Use Grep to find usage of deprecated or changed APIs:

Grep: "[deprecated-function-name]" Grep: "[changed-import-pattern]"

Document which files are affected and what changes are needed.

Phase 5: User Confirmation

For each major update, present:

• Package name and version transition

• Breaking changes found (summarized)

• Files potentially affected (count and list)

Use AskUserQuestion to confirm:

Header: "Confirm" Options:

• Proceed - Continue with upgrades and migrations

• Show details - Display detailed breaking changes for review

• Skip package - Exclude a specific package from upgrade

• Abort - Cancel the upgrade process

If "Show details" selected, display full migration research, then ask again.

Phase 6: Execute Upgrades

For Cautious Strategy

First, upgrade minor and patch only:

ncu -u --target minor npm install

Run tests to verify:

npm test

If tests fail, stop and inform user before proceeding with major upgrades.

Upgrade Major Versions

For each major version upgrade (or all at once based on strategy):

Single package:

ncu -u --filter [package-name] npm install

All packages:

ncu -u npm install

Phase 7: Apply Migrations

For each major update with identified code changes:

Step 1: Run Codemods (if Available)

Some packages provide automated migration tools:

• React: npx react-codemod [transform-name]

• Jest: npx jest-codemods

• Next.js: npx @next/codemod [transform-name]

Step 2: Manual Code Changes

For changes requiring manual intervention:

• Read the affected file

• Apply the necessary transformation using Edit

• Show the user what changed

Step 3: Update Configuration Files

If configuration format changed:

• Read current config

• Transform to new format

• Write updated config

Phase 8: Verification

Run available verification commands:

npm test

If build script exists:

npm run build

If lint script exists:

npm run lint

Report Results

Summarize:

• Packages upgraded (count)

• Breaking changes addressed (count)

• Files modified (count)

• Test results: pass/fail

• Remaining manual tasks (if any)

Recommend Next Steps

If any migrations could not be automated:

• List specific changes the user needs to review

• Highlight deprecated patterns that need attention

• Note any runtime behavior changes to watch for

Error Handling

ncu Not Available

If ncu is not found, suggest:

npm install -g npm-check-updates

Network Errors During Research

If WebSearch/WebFetch fails:

• Retry with alternative search terms

• Provide manual research links

• Proceed with caution, warning user that migration research may be incomplete

Test Failures After Upgrade

• Stop the upgrade process

• Suggest rollback: git checkout package.json package-lock.json && npm install

• Identify which package likely caused the failure

Migration Research Incomplete

If official migration docs are not found:

• Check npm package page for links

• Search GitHub issues for migration discussions

• Note as "migration research incomplete - proceed with caution"