Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
ln-711-npm-upgrader
Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-710-dependency-upgrader
Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.
Overview
| Aspect | Details |
|---|
| Input | Project path, package manager type |
| Output | Updated package.json, lock file, migration report |
| Supports | npm, yarn (classic & berry), pnpm |
Workflow
See diagram.html for visual workflow.
Phases: Pre-flight → Analyze → Security Audit → Check Outdated → Identify Breaking → Apply Upgrades → Apply Migrations → Verify Build → Report
Phase 0: Pre-flight Checks
| Check | Required | Action if Missing |
|---|
| Lock file (package-lock.json, yarn.lock, pnpm-lock.yaml) | Yes | Warn and run npm install first |
| package.json | Yes | Block upgrade |
Workers assume coordinator (ln-710) already verified git state and created backup.
Phase 1: Analyze Dependencies
Read package.json and categorize dependencies for upgrade priority.
Dependency Categories
| Category | Examples | Priority |
|---|
| framework | react, vue, angular | 2 (after peer deps) |
| build | vite, webpack, esbuild | 3 |
| ui | @radix-ui/*, tailwindcss | 4 |
| state | @tanstack/react-query, zustand | 5 |
| utils | lodash, date-fns | 6 |
| dev | eslint, prettier, typescript | 7 |
| peer | @types/*, typescript | 1 (first) |
Phase 2: Security Audit
Commands
| Manager | Command |
|---|
| npm | npm audit --audit-level=high |
| yarn | yarn audit --level high |
| pnpm | pnpm audit --audit-level high |
Actions
| Severity | Action |
|---|
| Critical | Block upgrade, report |
| High | Warn, continue |
| Moderate/Low | Log only |
Phase 3: Check Outdated
Commands
| Manager | Command |
|---|
| npm | npm outdated --json |
| yarn | yarn outdated --json |
| pnpm | pnpm outdated --json |
Phase 4: Identify Breaking Changes
Detection
MANDATORY READ: Load breaking_changes_patterns.md for full patterns.
- Compare current vs latest major versions
- Check breaking_changes_patterns.md for known patterns
- Query Context7/Ref for migration guides
Common Breaking Changes
| Package | Breaking Version | Key Changes |
|---|
| react | 18 → 19 | JSX Transform, ref as prop |
| vite | 5 → 6 | ESM only, Node 18+ |
| eslint | 8 → 9 | Flat config required |
| tailwindcss | 3 → 4 | CSS-based config |
| typescript | 5.4 → 5.5+ | Stricter inference |
Phase 5: Apply Upgrades
Upgrade Order
- Peer dependencies (TypeScript, @types/*)
- Framework packages (React, Vue core)
- Build tools (Vite, webpack)
- UI libraries (after framework)
- Utilities (lodash, date-fns)
- Dev dependencies (testing, linting)
Commands
| Manager | Command |
|---|
| npm | npm install <package>@latest --save |
| yarn | yarn add <package>@latest |
| pnpm | pnpm add <package>@latest |
Peer Dependency Conflicts
| Situation | Solution |
|---|
| ERESOLVE error | npm install --legacy-peer-deps |
| Still fails | npm install --force (last resort) |
MCP Tools for Migration Search
Priority Order (Fallback Strategy)
| Priority | Tool | When to Use |
|---|
| 1 | mcp__context7__query-docs | First choice for library docs |
| 2 | mcp__Ref__ref_search_documentation | Official docs and GitHub |
| 3 | WebSearch | Latest info, community solutions |
Context7 Usage
| Step | Tool | Parameters |
|---|
| 1. Find library | mcp__context7__resolve-library-id | libraryName: "react", query: "migration guide" |
| 2. Query docs | mcp__context7__query-docs | libraryId: "/facebook/react", query: "react 18 to 19 migration" |
MCP Ref Usage
| Action | Tool | Query Example |
|---|
| Search | mcp__Ref__ref_search_documentation | "react 19 migration guide breaking changes" |
| Read | mcp__Ref__ref_read_url | URL from search results |
WebSearch Fallback
Use when Context7/Ref return no results:
"<package> <version> breaking changes migration {current_year}""<package> <error message> fix stackoverflow"
Phase 6: Apply Migrations
Process
- Use MCP tools (see section above) to find migration guide
- Apply automated code transforms via Edit tool
- Log manual migration steps for user
Do NOT apply hardcoded migrations. Always fetch current guides via MCP tools.
Phase 7: Verify Build
Commands
| Check | Command |
|---|
| TypeScript | npm run check or npx tsc --noEmit |
| Build | npm run build |
| Tests | npm test (if available) |
On Failure
- Identify failing package from error
- Search Context7/Ref for fix
- If unresolved: rollback package, continue with others
Phase 8: Report Results
Report Schema
| Field | Description |
|---|
| project | Project path |
| packageManager | npm, yarn, or pnpm |
| duration | Total time |
| upgrades.major[] | Breaking changes applied |
| upgrades.minor[] | Feature updates |
| upgrades.patch[] | Bug fixes |
| migrations[] | Applied migrations |
| skipped[] | Already latest |
| buildVerification | PASSED or FAILED |
| warnings[] | Non-blocking issues |
Configuration
Options:
# Upgrade scope
upgradeType: major # major | minor | patch
# Breaking changes
allowBreaking: true
autoMigrate: true
queryMigrationGuides: true # Use Context7/Ref
# Security
auditLevel: high # none | low | moderate | high | critical
minimumReleaseAge: 14 # days
# Peer dependencies
legacyPeerDeps: false
force: false
# Verification
runBuild: true
runTests: false
runTypeCheck: true
# Rollback
createBackup: true
rollbackOnFailure: true
Error Handling
| Error | Cause | Solution |
|---|
| ERESOLVE | Peer dep conflict | --legacy-peer-deps |
| ENOENT | Missing lock file | npm install first |
| Build fail | Breaking change | Apply migration via Context7 |
| Type errors | Version mismatch | Update @types/* |
Rollback
Restore package.json and lock file from git, then run clean install to restore previous state.
References
Definition of Done
- Lock file and package.json verified present
- Dependencies categorized and prioritized (peer deps first)
- Security audit completed (critical blocks upgrade)
- Outdated packages identified via
npm/yarn/pnpm outdated - Breaking changes detected via breaking_changes_patterns.md and MCP tools
- Upgrades applied in priority order with rollback on failure
- Build and type checks pass after upgrades
- Report returned with major/minor/patch counts, migrations, and build status
Version: 1.1.0 Last Updated: 2026-01-10
