---
name: dependency-update-pass
description: Use when asked to update a website's or web app's packages (npm, pnpm, yarn, Composer, pip, etc.), fix vulnerability alerts, clean up lockfiles, or set up automated updates with Renovate or Dependabot. Audits first, updates in small batches by risk, verifies build, tests, and visuals, and delivers one review PR per batch with a rollback note. Not for adding new libraries or rewriting code to a new framework.
---

# Dependency update pass

Last reviewed: 2026-11-10

## Quick prompts

For anyone improving a site or app, whether a small-business owner or someone at a larger company practicing better prompts. Outdated software is the most common way sites get hacked, and small regular updates are far cheaper than one big forced upgrade. Paste a prompt into any AI assistant that can see the site or repo.

1. "Here is the output of npm audit (or our update report) for the project I work on: [paste]. Turn it into a plain-English plan: what is urgent, what can wait, and why. No changes yet."
   *Why this prompt works:* Paste real output so the plan is based on facts, not guesses.

2. "Check which packages in the repo I work on are outdated. Group them into low, medium, and high risk to update, with one line each on why. Report before updating anything."
   *Why this prompt works:* Ask for risk groups so you can approve updates in safe batches.

3. "Is the Node, PHP, or Python version the project I work on uses still supported? Tell me the end-of-support date and what upgrading would involve, before making changes."
   *Why this prompt works:* One focused question gets a precise, checkable answer.

## Why this matters (say this to non-technical owners)

- Most real-world web compromises use known holes in old software, and fixes ship as package updates.
- Small regular updates are cheap; skipping a year turns into a risky rewrite when a forced upgrade comes (security fix, host drops an old Node or PHP version).
- The package ecosystem itself gets attacked (hijacked maintainer accounts publishing malicious versions). Lockfiles, a short wait before adopting brand-new releases, and reviewing what changed are the defenses.

## Hard limits

- Update only; no feature work and no unrelated refactors.
- One review PR per batch. Do not merge or deploy to production without the owner's approval. If CI/deploy minutes are metered, push once per batch.
- Never run install scripts from an unknown new package without noting it; never print tokens from `.npmrc` or CI secrets.
- Do not delete and regenerate a lockfile wholesale unless that is the explicit goal; it silently upgrades everything.

## Inputs to gather

1. Package manager and version (`packageManager` field, lockfile type), runtime version (`.nvmrc`, `engines`, host setting).
2. Build, test, lint, and type-check commands; how previews are built.
3. Existing automation (`.github/dependabot.yml`, `renovate.json`), open update PRs, and alert list.
4. Key routes to check visually after updates.

## Step 1: Audit (no changes)

- Clean install from the lockfile: `npm ci` / `pnpm install --frozen-lockfile` / `yarn install --immutable`.
- Vulnerabilities: `npm audit` (or `pnpm audit`, `yarn npm audit`, `composer audit`, `pip-audit`). Record severity, whether the vulnerable package is a runtime or dev/build-only dependency, and whether the vulnerable code path is reachable.
- Supply-chain sanity: `npm audit signatures` where supported; flag packages with install scripts; check for packages that are unmaintained or deprecated.
- Outdated: `npm outdated` / `pnpm outdated`. Group results into patch, minor, major.
- Runtime: is the Node/PHP/Python version still supported upstream? Note end-of-life dates.

## Step 2: Plan batches (by risk)

1. **Security fixes** for runtime dependencies first, smallest version that fixes it.
2. **Patch and minor** updates, grouped (for example all lint tooling, all test tooling, framework + its official plugins together).
3. **Major** updates, one per PR, after reading the changelog and migration guide.
4. **Runtime** version bumps alone in their own PR.

Respect semver ranges, but do not trust them blindly: a 0.x package can break on a minor. Prefer releases that are a few days old (a cooldown) unless it is a security fix.

## Interface-type notes

- **Static/SSR content sites**: framework and its integrations (image, markdown, sitemap, search index) must move together; check that page count and URLs are unchanged after the build.
- **SPAs and apps**: check bundle size change, router and state library majors, and auth SDKs carefully.
- **CMS (WordPress etc.)**: core, plugins, and themes update through the CMS or Composer; take a backup first and test on staging.
- **E-commerce**: payment SDK updates only with a test-mode checkout run.

## Step 3: Update and verify each batch

- Apply the batch, commit lockfile and manifest together.
- Run: clean install, build, tests, lint, type-check.
- Compare build output: page count, route list, bundle sizes, warnings.
- Visual smoke test in a real browser on key templates (desktop and phone, both themes if any). Screenshot diffs if the project has them.
- Re-run the audit; note what is fixed and what remains (with reason, for example "dev-only, not shipped").

## Rollback

- Each batch is one PR, so rollback is reverting that PR (lockfile included) and redeploying the previous build. Note the previous deployment ID if the host keeps deployment history.

## Automate (propose, do not enable without approval)

- Dependabot or Renovate with grouped updates, a weekly schedule, and a cooldown (Dependabot `cooldown`, Renovate `minimumReleaseAge`) for version updates while security updates still come right away.
- Auto-merge only for dev-dependency patches that pass CI, and only if the owner wants it.
- CI runs `npm ci` (frozen lockfile), build, tests, and `npm audit --audit-level=high` on every update PR.

## Report format

1. Audit summary: counts by severity, outdated by patch/minor/major, runtime EOL status.
2. Per batch: packages and versions (from → to), why, changelog notes that matter, checks run and results, PR link ("not merged").
3. Remaining issues and why they were deferred.
4. Proposed automation config (as a diff, not applied).

## References

- npm audit: https://docs.npmjs.com/cli/commands/npm-audit
- npm ci: https://docs.npmjs.com/cli/commands/npm-ci
- pnpm audit: https://pnpm.io/cli/audit
- Semantic Versioning: https://semver.org/
- Dependabot options (groups, cooldown): https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference
- Renovate minimum release age: https://docs.renovatebot.com/key-concepts/minimum-release-age/
- OWASP Top 10 (vulnerable/outdated components and software supply chain): https://owasp.org/www-project-top-ten/
- OpenSSF Scorecard: https://scorecard.dev/
- Node.js release schedule: https://nodejs.org/en/about/previous-releases
