Migrate

Migrate — Dependency Management

Safe dependency updates with breaking change detection and resolution.

Usage

Step 1: Audit Current State

# List outdated packages
npm outdated 2>/dev/null || true

# Check for known vulnerabilities
npm audit --json 2>/dev/null | node -e "const d=require('fs').readFileSync(0,'utf8');try{const a=JSON.parse(d);console.log('Vulnerabilities:',a.metadata?.vulnerabilities?.total||0)}catch{}"

# Current package counts
node -e "const p=require('./package.json');console.log('deps:',Object.keys(p.dependencies||{}).length,'devDeps:',Object.keys(p.devDependencies||{}).length)"

Step 2: Classify Updates

Sort all outdated packages into safety tiers:

Step 3: Safe Updates (Patch + Minor)

# Update all patch and minor versions
npx npm-check-updates -u --target minor
npm install

# Verify nothing broke
npm run typecheck 2>/dev/null
npm run build
npm test -- --passWithNoTests --watchAll=false 2>/dev/null

If any check fails, revert and update one package at a time to isolate the issue.

Step 4: Major Updates (One at a Time)

For each major update:

1. Read the changelog/migration guide:

   # Check the package's release notes
   npm info [package] changelog 2>/dev/null || echo "Check GitHub releases"
   

   If mcp__plugin_context7_context7__* tools are available, prefer them over WebSearch for version-specific breaking changes:

   resolve-library-id({ libraryName: "Next.js", query: "migrating from 14 to 15" })
   query-docs({ libraryId: "/vercel/next.js/v15.3.0", query: "breaking changes from v14" })
   

   Context7 returns version-pinned docs, which avoids the common trap of applying stale migration advice from old blog posts.

2. Update and test:

   npm install [package]@latest
   npm run typecheck 2>/dev/null
   npm run build
   

3. Fix breaking changes — common patterns:

   Breaking Change	How to Fix
   API renamed	Find-and-replace old → new names
   Config format changed	Update config file to new schema
   Peer dep mismatch	Update related packages together
   Type signature changed	Update interfaces and type assertions
   Removed feature	Replace with recommended alternative

4. Commit separately — one commit per major update for easy revert

Step 5: Security Fixes

# Auto-fix what's safe
npm audit fix

# For breaking fixes that need major updates
npm audit fix --force --dry-run  # Preview first

Review --force changes before applying — they may introduce breaking changes.

Step 6: Report

Dependency Migration
═══════════════════

Updated: [N] packages
- [N] patch updates (safe)
- [N] minor updates (safe)
- [N] major updates (breaking changes resolved)
- [N] security fixes

Skipped: [N] packages
- [package]: pinned at X.Y.Z because [reason]

Vulnerabilities: [before] → [after]

All checks pass: typecheck ✓ build ✓ tests ✓

Rules

• Never update all major versions at once — one at a time
• Always run typecheck + build + tests after each update
• Commit patch/minor updates together, major updates separately
• If a major update breaks things and the fix isn't obvious, defer it and note why
• Check if lockfile (package-lock.json) is committed — if yes, commit the updated lockfile too