NPM Package Maintenance

Gotchas

• Override target must be a FIXED version — The most common failure mode: adding "vite": ">=7.3.2" to pnpm.overrides lets pnpm silently install 8.x.y on the next install, causing major-version cascading regressions. Override targets must be exact ("vite": "7.3.2"). See "Override Safety Rule" below for the real-incident reference from April 2026. The LEFT side of an override may carry a range (to select affected versions); the RIGHT side must be fixed.
• An EXACT override target can still be vulnerable — exact is necessary but NOT sufficient: the target must also be >= the advisory's fixed-in version. Pinning uuid to 11.1.0 (exact, same major) when the fix landed in 11.1.1 leaves the advisory open — the override silently "works" but resolves a still-vulnerable version. After EVERY override, re-run audit and confirm the targeted package is gone. If it still appears, the target is one patch too low or the selector mis-scoped — bump it; do NOT record it as "blocked" or "needs a framework update".
• npm audit and pnpm audit disagree on the same dependencies — different package managers resolve transitive versions differently (pnpm floats to the newest in-range patched release; npm can keep an older locked one) and the override block lives in different places: overrides (npm), pnpm.overrides (pnpm), resolutions (yarn). A reference starter reporting "0 vulnerabilities" under pnpm does NOT mean an npm-based consumer is clean. Always audit with the PROJECT's own package manager, and target the patched versions the reference resolves to.
• pnpm audit --fix --force can cause major version jumps — Step 3 of the escalation ladder is destructive. It will happily upgrade a transitive dependency from ^1.x to 3.x if that closes the CVE. Always verify pnpm run build and the full test suite after using it, and prefer a scoped override for transitives where a compatible patch exists.
• Deprecated packages in devDependencies often lag — @types/* packages in particular remain flagged as deprecated for months after the upstream merges types natively. Don't remove them blindly — check the affected imports still resolve via the new inline types before deleting.
• packageManager field locks pnpm/npm/yarn version — When running maintenance across a monorepo, the packageManager: "pnpm@X.Y.Z" field in the root package.json pins the exact version. Upgrading pnpm without also bumping this field causes CI and local runs to diverge silently.

When to Use This Skill

• User mentions outdated packages or wants to update dependencies
• Security vulnerabilities found via pnpm audit
• Need to optimize dependencies vs devDependencies
• Removing unused packages from package.json
• Pre-release or post-feature dependency cleanup
• General package maintenance or housekeeping tasks