Skip to content

refactor(template): upgrade the base to astro 7 and exact pins - #45

Open
mimukit wants to merge 2 commits into
mainfrom
issue-41-upgrade-the-base-to-astro-7-and-exact-pins
Open

refactor(template): upgrade the base to astro 7 and exact pins#45
mimukit wants to merge 2 commits into
mainfrom
issue-41-upgrade-the-base-to-astro-7-and-exact-pins

Conversation

@mimukit

@mimukit mimukit commented Aug 1, 2026

Copy link
Copy Markdown
Owner

Summary

Phase 0 of the UI blocks plan (docs/plans/plan-ui-blocks-2026-08-01.md): move the base template from Astro 5 to Astro 7 before the new design layer lands on it, so the foundation gets built once rather than twice. Behavior-preserving and independent of the rest of epic #40.

Two majors of Astro were skipped by design, not neglect — ADR 0016's resolver caps within the current major, so this is the deliberate --allow-major crossing. Alongside the bump, every remaining ^ range in the template is migrated to an exact pin, which is what the pin-style convention already calls for (deps:update treats surviving ranges as pending migrations).

The v6/v7 breaking-change surface was surveyed on the issue and each item verified against the actual template: Astro.glob() is unused (index.astro already uses import.meta.glob), src/fetch.ts doesn't exist, and the @web Vite alias is a plain string entry, so nothing in astro.config.mjs needed to change. The two behavioral risks — v7's mandatory strict Rust compiler and the compressHTML default flipping true'jsx' — were both cleared empirically: all three pages compile with no strict-HTML errors, and an Astro 5 vs Astro 7 built-HTML diff showed every whitespace delta sitting between block elements. The one inline hotspot, <a>Terms</a> · <a>Privacy</a>, survives intact, so no {" "} fixes were needed.

Closes #41

Changes

  • apps/web on the Astro 7 line. astro@7.1.6, @astrojs/react@6.0.2 (the 6.x line is the one that targets Astro 7 / Vite 8 — 5.x mismatches), react/react-dom@19.2.8, plus matching @types/react@19.2.17 and @types/react-dom@19.2.3. Transitive Vite resolves to 8.2.0, confirming the Rolldown line actually installed rather than falling back to Vite 7.
  • Every ^ range in the template is now an exact pin. @types/node@24.13.3, wrangler@4.115.0 in apps/web; turbo@2.10.7, typescript@5.9.3 at the template root; @types/react@19.2.17 and react@19.2.8 in packages/ui, including its peerDependencies.react.
  • wrangler.jsonc compatibility_date2026-07-22, matching workerd 1.20260722.1 as bundled with wrangler 4.115.0. Cosmetic for a pure static-asset deployment, but it silences the fallback-date warning.
  • docs(qa) — manual QA plan at docs/qa/qa-astro-7-base-template-2026-08-01.md: 7 cases (4 critical) plus the automated checks already run.

astro.config.mjs is untouched — no v7 config-shape change affects it, and the @web alias and its explanatory comment are preserved verbatim.

Assumptions worth a reviewer's eye

  • The Astro-line pins are verbatim from the issue's acceptance criteria. Note astro@7.1.6 was published 2026-07-29, so it sits just inside the repo's own 3-day ADR-0016 cooldown (clears 2026-08-03) — but comfortably outside pnpm's 1-day install-time cooldown, so downstream saasaloy init is unaffected.
  • turbo, wrangler, and the @types/* pins are the resolver's cooldown-eligible versions, deliberately not absolute npm latest. A first pass pinning absolute latest (turbo@2.10.8, wrangler@4.118.0 — both under a day old) caused pnpm install in the playground to silently append 8 minimumReleaseAgeExclude entries to the generated project's own pnpm-workspace.yaml. That mutation would land on every downstream saasaloy init. The pins as merged leave pnpm-workspace.yaml untouched — verified explicitly.
  • @types/node stays on major 24 and typescript on major 5. Majors deliberately not crossed; the issue scopes the major bump to the Astro line only. Both surface as informational major-available rows in deps:check.
  • peerDependencies.react in packages/ui is pinned exact, taking "every remaining ^ range" literally. Worth flagging that pnpm deps:update does not scan the peerDependencies bucket, so this one pin is maintained by hand.

Known follow-ups (none introduced here)

  • deps:verify's typecheck leg is vacuous. templates/base/turbo.json declares a typecheck task but no template package defines a typecheck script, so turbo run typecheck executes 0 tasks. Pre-existing on main; worth its own issue so the gate actually gates.
  • Wrangler version skew. The template now pins 4.115.0 while modules/api and modules/database still pin 4.113.0. Pre-existing drift already flagged by deps:check; a routine pnpm deps:update converges it. Out of scope here.
  • pnpm deps:check exits non-zero, entirely from that pre-existing module drift plus natural aging past the pins chosen here. No template row is actionable — zero range→exact rows remain.
  • Astro 7 daemonizes a direct astro dev invocation (it returns to the prompt and prints Stop: astro dev stop). The documented path is unaffected: pnpm devturbo run dev keeps astro dev in the foreground and persistent, watching for changes.

Test plan

Automated (all green — recorded in the QA doc's Automated verification section):

  • pnpm deps:verify green from a destroyed playground — install resolved 410 packages with no peer warnings, cache-bypassed Astro 7 build, all 3 pages built under the Rust compiler with no strict-HTML errors
  • pnpm-workspace.yaml not mutated by install (the main regression risk)
  • Transitive Vite is 8.2.0 (Rolldown line, not a Vite 7 fallback)
  • Astro 5 vs Astro 7 built-HTML diff — every whitespace delta between block elements; <a>Terms</a> · <a>Privacy</a> intact
  • @web alias resolves under Vite 8 (confirmed via a temporary probe island, since removed)
  • astro dev serves /, /terms, /privacy — all 200
  • wrangler deploy --dry-run exits 0 with no compatibility-date warning

Manual (see docs/qa/qa-astro-7-base-template-2026-08-01.md — 7 cases, 4 critical):

  • TC-1 Landing page / renders correctly in a browser
  • TC-2 Terms · Privacy separator keeps its spaces under compressHTML: 'jsx'
  • TC-3 /terms and /privacy render and link back home
  • TC-4 A fresh saasaloy init + install leaves pnpm-workspace.yaml untouched

mimukit added 2 commits August 1, 2026 19:29
Upgrade the base template to Astro 7 (from 5) and migrate all remaining semver ranges to exact version pins for reproducible scaffolds.

- Bump astro from ^5 to 7.1.6 and @astrojs/react from ^5 to 6.0.2
- Update react and react-dom to exact 19.2.8
- Update @types/node to 24.13.3, @types/react to 19.2.17, @types/react-dom to 19.2.3
- Update wrangler to 4.115.0 and compatibility_date to 2026-07-22
- Pin turbo to 2.10.7 and typescript to 5.9.3 in workspace root
- Pin react and @types/react to exact versions in packages/ui
Manual QA plan for Astro 5→7 base template upgrade (issue #41) with exact-pin validation.

- Covers Astro 7 upgrade from Astro 5
- Exact-pin validation for all template dependencies
- Test cases for scaffold, build, serve, and visual consistency
- References issue #41 and UI blocks plan phase 0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor(template): upgrade the base to astro 7 and exact pins

1 participant