Monthly Dependency Updates — Design

Date: 2026-07-27
Repo: C-Mejlak/property-in-gozo-11ty (11ty static site, CloudCannon CMS, GitHub main)
Status: Approved, ready for implementation plan

Goal

A repeatable, human-executed monthly runbook that keeps the project's npm dependencies current and its dependency security advisories resolved, without breaking the build or the site's appearance.

Non-goals

No GitHub bot (Dependabot / Renovate). Updates are performed manually by choice.
No CI workflow, no snapshot testing, no helper scripts. Verification is npm run build plus a manual visual check.
No separate update log file. Git history and the monthly PR description serve as the record.

Decisions (from brainstorm)

Question	Decision
Automation approach	Manual monthly checklist
Version range covered	Everything incl. majors
Build verification	`npm run build` + manual visual check
Branch workflow	Branch then merge to `main`
Runbook format	Markdown checklist, no scripts
Session structure	Risk-tiered phases (patch batch → minor batch → each major individually → audit fix)

Deliverable

A single new file: docs/dependency-update-runbook.md. No code or config changes outside docs/.

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. This is the first use of conventional commits in this repo; the convention applies to dep work only and does not impose a project-wide standard.
- 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 (core mental model)

For each row in npm outdated, compare Current / Wanted (max version satisfying 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 command per phase:

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

Current project state, pre-categorized (from npm outdated at design time):

Dep	Current	Wanted	Latest	Patch	Minor	Major
@11ty/eleventy	3.1.2	3.1.6	3.1.6	→3.1.6	–	–
@11ty/eleventy-upgrade-help	3.0.1	3.0.2	3.0.2	→3.0.2	–	–
alpinejs	3.15.0	3.15.12	3.15.12	→3.15.12	–	–
tailwindcss	3.4.17	3.4.19	4.3.3	→3.4.19	–	→4.3.3
autoprefixer	10.4.21	10.5.4	10.5.4	–	→10.5.4	–
postcss	8.5.6	8.5.23	8.5.23	→8.5.23	–	–
postcss-preset-env	10.4.0	10.6.1	11.3.2	–	→10.6.1	→11.3.2

This table is illustrative; the runbook re-derives it from a fresh npm outdated each month.

Phased procedure

Phase 0 — Prep

git checkout main && git pull --ff-only
git checkout -b chore/dep-updates-YYYY-MM
npm outdated → record Current / Wanted / Latest for every dep; tier each row per the rule above.
npm audit --omit=dev → record open advisories (severity + advisories count).

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:

npm install <pkg>@latest
Consult the "Known tricky majors" appendix; apply listed migration steps.
npm run build → must succeed.
npm run dev → visual check across the pages listed below.
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

npm audit --omit=dev → see what remains.
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 force --force or hand-edit the lockfile.

Phase 5 — Final verification & merge

npm run dev → full visual check across the pages below.
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 and confirm layout, Tailwind styling, and Alpine interactions work:

/ — 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/

Rollback

Each phase is its own commit. To 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 (appendix)

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 PostCSS plugin in postcss.config.js.
tailwind.config.js becomes optional / legacy; v4 prefers CSS @theme blocks.
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 runbook's defer escape hatch 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 (manual by design).

Open questions

None.