Monthly Dependency Update Runbook

A repeatable, human-executed checklist for keeping this project's npm dependencies current and its security advisories resolved. No bots, no CI — just this runbook, once a month.

How to use this runbook

Cadence: First week of every month.
Expected time: 20–60 minutes depending on how many majors need attention.
What you need: A local checkout of this repo, Node.js installed, and a browser.
Before you start: Skim the Known tricky majors appendix so you know which upgrades might need extra work.

Branch & commit conventions

Branch: chore/dep-updates-YYYY-MM (e.g. chore/dep-updates-2026-07), cut from latest main.
One commit per phase, conventional-commit style:
- Phase 1: chore(deps): bump patch versions YYYY-MM
- Phase 2: chore(deps): bump minor versions YYYY-MM
- Phase 3: chore(deps)!: bump <pkg> to v<N> — one commit per major
- Phase 4: chore(security): npm audit fix YYYY-MM
PR title: chore(deps): monthly dependency updates YYYY-MM, merged to main after the final visual check passes.

Semver tiering rule

For each row in npm outdated, compare Current / Wanted (max version satisfying the package.json range) / Latest (newest published):

Patch tier: Wanted shares the same major.minor as Current → target Wanted.
Minor tier: Wanted is a higher minor within the same major as Current → target Wanted.
Major tier: Latest is a higher major than Current → first reach Wanted (in the patch or minor phase, as appropriate for that dep), then target Latest in the major phase, one dep at a time.

Install commands:

Patch / minor phases: npm install <pkg>@<Wanted> (use the Wanted version from npm outdated).
Major phase: npm install <pkg>@latest (the Latest version), one dep at a time.

Phased procedure

Phase 0 — Prep

[ ] git checkout main && git pull --ff-only
[ ] git checkout -b chore/dep-updates-YYYY-MM
[ ] Run npm outdated → for each dep, record Current / Wanted / Latest and tier it per the rule above.
[ ] Run npm audit --omit=dev → note the severity and count of open advisories.

Phase 1 — Patches

[ ] For each patch-tier dep: npm install <pkg>@<Wanted>
[ ] npm run build → must succeed with no errors.
[ ] Commit: chore(deps): bump patch versions YYYY-MM

Phase 2 — Minors

[ ] For each minor-tier dep: npm install <pkg>@<Wanted>
[ ] npm run build → must succeed.
[ ] Commit: chore(deps): bump minor versions YYYY-MM

Phase 3 — Majors (one dep at a time)

For each major-tier dep, one at a time:

[ ] npm install <pkg>@latest
[ ] Consult the Known tricky majors appendix; apply any listed migration steps.
[ ] npm run build → must succeed.
[ ] npm run dev → visual check across the Visual check pages.
[ ] Defer escape hatch: if the build or visual check fails and the fix is not quick, revert that dep only:
```
git checkout package.json package-lock.json && npm ci
```
Note the deferral with reason in the PR, and move on. Do not force a stuck major.
[ ] Commit (only if not deferred): chore(deps)!: bump <pkg> to v<N>

Phase 4 — Security audit

[ ] Run npm audit --omit=dev → see what remains after the version bumps.
[ ] npm audit fix → apply safe fixes.
[ ] npm run build → must succeed.
[ ] Commit: chore(security): npm audit fix YYYY-MM
[ ] Any remaining unfixable advisories (typically transitive deps awaiting an upstream release) → note in the PR. Do not use --force or hand-edit the lockfile.

Phase 5 — Final verification & merge

[ ] npm run dev → full visual check across the Visual check pages.
[ ] git fetch origin && git rebase origin/main (CloudCannon may have pushed content meanwhile).
[ ] npm run build → must pass after the rebase.
[ ] Push branch; open PR titled chore(deps): monthly dependency updates YYYY-MM. PR body contains:
- Summary table of bumps (per dep: from → to, tier)
- Advisories fixed by npm audit fix
- Any majors deferred, with reasons
- Any advisories still open, with reasons
[ ] Merge to main.

Visual check pages

After npm run dev, visit each of these in your browser and confirm layout, Tailwind styling, and Alpine interactions work as expected:

/ — home
/properties/ — listing index
/property-in-victoria/ (or /nadur/, /gharb/, /xaghra/) — a location page
/search/ — search page (Alpine-driven)
/favourites/ — favourites page (Alpine-driven)
/contact-us/
/buying-guide/

What to look for: page renders without errors, Tailwind classes applied (colors, spacing, container width), Alpine-powered interactions work (search filtering, favourites toggle), no broken layouts or missing styles.

Rollback

Each phase is its own commit, so you can undo a specific tier:
```
git revert <commit>
```
or
```
git reset --hard <previous-phase-commit>
```
A deferred major leaves the branch clean for the remaining work; nothing is force-merged.

Known tricky majors

tailwindcss v4

CSS-first config. Migration touches the current PostCSS-based setup:

@import "tailwindcss"; replaces the @tailwind base; @tailwind components; @tailwind utilities; directives in css/tailwind.css.
The @tailwindcss/postcss plugin replaces the current tailwindcss plugin in postcss.config.js.
tailwind.config.js becomes optional / legacy; v4 prefers CSS @theme blocks. The current config has custom emerald colors, container settings, variants.extend, and the @tailwindcss/aspect-ratio plugin — all of which need porting to the v4 format.
The npm run dev and npm run build scripts invoke tailwindcss via npx tailwindcss ...; v4's CLI behavior differs and may require script changes.

The build will likely break the postcss.config.js / css/tailwind.css setup on first bump. This is realistic to defer to a dedicated session rather than attempt inside the monthly runbook. The defer escape hatch in Phase 3 exists precisely for this case.

postcss-preset-env v11

Check the changelog at bump time for stage / preset / breaking option changes. Lower risk than Tailwind v4, but verify CSS output is unchanged by the visual check.

Cadence

Monthly, first week of the month. No calendar automation — this runbook is the process. Git history and the monthly PR description serve as the update log.