| name | upgrade-dependencies |
| description | Upgrade all dependencies in an npm project to their latest versions. |
| disable-model-invocation | true |
Upgrade Dependencies
1. Sync main
git checkout main && git pull
2. Create branch
git checkout -b chore/upgrade-deps-$(date +%Y-%m-%d)
3. Inspect outdated packages
npm outdated
npm outdated walks the workspace tree by default. The Wanted column is the highest match for the existing range; Latest is the absolute newest. Anything where Latest > Wanted is a major bump.
4. Upgrade in priority order
Group upgrades by risk so a breakage is easy to bisect. Commit each group separately.
-
Patch + minor within existing ranges:
npm update --workspaces --include-workspace-root
This respects the semver ranges already in package.json, so it only pulls in patches and minors.
-
Major bumps — one package (or tightly-coupled set) at a time. Use npm-check-updates to rewrite the range, then reinstall:
npx npm-check-updates -u --filter <pkg>
npm install
For a workspace package, run ncu from inside that workspace directory or pass --packageFile packages/<name>/package.json. Read each package's CHANGELOG/release notes for breaking changes before bumping. Update call sites in the same commit.
-
devDependencies / build tooling (typescript, rollup, eslint, playwright, etc.) — bump last; these often need config tweaks.
Always verify with npm view <pkg> version that "latest" is what you got.
5. Overrides
If package-lock.json still pins an old transitive after a direct bump, add an overrides entry in the root package.json. Use range-keyed overrides ("<pkg>@<major>": "<version>") when different majors of the same package coexist in the tree — a flat override forces every consumer onto the same version and routinely breaks packages that depend on the old API. Confirm with npm ls <pkg> that each major resolves where you expect.
Remove any overrides entries that are now redundant (the direct dep already carries a safe version).
6. Verify
Use the validate skill after every group; fix failures before moving on.
If a major bump breaks the build and the migration is non-trivial, roll back that specific upgrade (npm install <pkg>@<previous>), note it in the PR body under "Deferred", and keep moving. Do not commit a broken build.
7. Commit, push, open PR
Use the commit skill with title chore: upgrade dependencies and body:
## Upgraded
- <pkg>: <old> → <new>
## Deferred (breaking, needs follow-up)
- <pkg> <old> → <new>: <reason>
