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-821-npm-upgrader
Type:
L3 Worker
Category:
8XX Optimization
Parent:
ln-820-dependency-optimization-coordinator
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
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
Git clean state
Yes
Block (need clean baseline for revert)
Workers assume coordinator (ln-820) already verified git state and created backup.
Worktree & Branch Isolation
MANDATORY READ:
Load
shared/references/git_worktree_fallback.md
— use ln-821 row.
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
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 breaking_changes_patterns.md npm_peer_resolution.md 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