Updating an npm Package

Use this skill when the user asks to update, upgrade, or bump a specific npm dependency.

Steps

1. Check the current version — read package.json to find the installed version:

   npm ls <package-name>
   

2. Find the latest version on npm — fetch the package info:

   npm view <package-name> versions --json
   npm view <package-name> dist-tags --json
   

   This gives you the latest tag and all published versions.

3. Determine the update type — compare current version to latest:

   • Patch (1.2.3 → 1.2.4): bug fixes only
   • Minor (1.2.3 → 1.3.0): new features, backwards compatible
   • Major (1.2.3 → 2.0.0): breaking changes

4. For patch or minor updates — just do it:

   npm install <package-name>@latest
   

   Run the build and tests to make sure nothing broke:

   npm run build && npm test
   

   If everything passes, commit and report what changed.

5. For major updates — do a thorough investigation first:

   a. Fetch the changelog and release notes — check the package's GitHub repo for CHANGELOG.md, MIGRATION.md, or release notes. Use the web to find the official upgrade guide:

   Search: "<package-name> v<major> migration guide" OR "<package-name> v<major> upgrade guide"
   

   b. Read the breaking changes — identify every breaking change between the current and target version. Common things to check:

   • Removed or renamed APIs
   • Changed function signatures or return types
   • Dropped Node.js version support
   • New peer dependency requirements
   • Changed default behavior
   • Config file format changes

   c. Scan the codebase for impact — search for every usage of the package:

   # Find all imports
   grep -r "from ['\"]<package-name>" src/
   grep -r "require(['\"]<package-name>" src/
   

   For each usage, check if it's affected by a breaking change.

   d. Apply the update:

   npm install <package-name>@latest
   

   e. Fix breaking changes — update each affected usage based on the migration guide. Apply changes file by file.

   f. Verify — run the full suite:

   npm run lint && npx tsc --noEmit && npm test && npm run build
   

   g. Produce a migration report — summarize:

   ## Package Update: <package-name> v<old> → v<new> (Major)
   
   ### Breaking Changes Applied
   - `oldFunction()` renamed to `newFunction()` — updated in 3 files
   - Config format changed from `.js` to `.config.ts` — migrated
   - Dropped support for Node 16 — verified we're on Node 20
   
   ### Files Modified
   - src/lib/client.ts — updated import and function call
   - src/config/settings.ts — migrated config format
   - package.json — bumped version
   
   ### Validation
   - ✅ Lint passes
   - ✅ TypeScript compiles
   - ✅ All 47 tests pass
   - ✅ Build succeeds
   

Notes

• Always check peer dependency compatibility before updating — npm install will warn about mismatches.
• For monorepos, check if the package is used in multiple workspaces and update them all together.
• If the package has a codemod tool (e.g. npx @next/codemod), use it instead of manual migration.
• Lock file (package-lock.json) changes are expected — commit them with the update.