Plain HTML, Astro, React Or Next For Sydney Property Project?[1][2]

A decision note for the Sydney property guide at branch syd-prop-deciding-framework, commit 87412b3. The branch is a frozen reference point for this comparison, not a framework migration branch.[3]

Current Static Reference Pages

Mostly explanatory HTML pages with shared navigation, diagrams, glossary, and process notes.

Interactive Small Tools

Amortization calculator, notes editor, and admin report use light browser JavaScript.

Server Cloudflare Worker + D1

_worker.js handles Access logging, notes, /api/me, and superadmin reporting.

Question Framework Cost

The key question is whether a framework removes more complexity than it adds.

Recommendation Now

Stay with plain HTML/CSS/JS plus Cloudflare Pages Worker for now. The app is static-first, the backend is already small and explicit, and the current deployment path is easy to reason about.[8]

The biggest pain is duplicated header/layout markup. That can be solved with a tiny build/template step[4], or later with Astro if the content model grows.

Most Likely Future Move

If the guide keeps growing, Astro is the cleanest next step. Astro is content-first, ships zero JavaScript by default, and lets you add interactive islands only where needed.[5]

That matches this project better than making every page part of a client-heavy app shell.

Option Fit For Current Project What It Improves What It Adds
Plain HTML/CSS/JS Best current fit. Lowest complexity, direct Cloudflare Pages deploy, simple Worker/D1 mental model. Repeated headers/layouts, manual linking, no content components.
Astro Best future framework fit. Shared layouts/components, static output, content collections, optional UI islands.[5] Build step, Astro conventions, some migration work.
React Useful only if interactivity grows substantially. Reusable interactive components and mature client state patterns.[6] Client app complexity, routing/build choices, more JavaScript than most pages need.
Next.js Too much for the current shape. Full-stack React framework, routing, rendering strategies, API/server capabilities.[7] Framework/runtime complexity, Cloudflare compatibility decisions, more moving parts than this project currently needs.

Stay Plain When

  • Pages are mostly explanatory.
  • Interaction is limited to small scripts.
  • The Worker is easy to audit.
  • Deployment simplicity matters more than component abstraction.

Choose Astro When

  • More pages create layout duplication.
  • Glossary/process content should become structured collections.
  • You want reusable page components without a full client app.
  • Static-first output remains the priority.

Avoid Next Until

  • There are many authenticated app workflows.
  • Server-rendered React routes matter.
  • Backend-for-frontend logic becomes large.
  • The team accepts a heavier framework contract.

Migration Path

Phase 0: current plain HTML/CSS/JS
  keep Pages + _worker.js + D1

Phase 1: small template/build script
  generate repeated headers and shared page shell
  see shared-header-template branch

Phase 2: Astro if content grows
  layouts, components, content collections

Phase 3: React islands only where needed
  calculator, notes, admin tables

Decision Rule

Do not migrate because “frameworks are cleaner” in the abstract. Migrate when repeated layout/content structure costs more than the build and framework conventions.

For this exact project, Astro is the likely upgrade. React/Next are only justified if the product becomes more app-like than reference-like.

Astro Vs build.mjs

At a very reductive level, Astro replaces the custom scripts/build.mjs approach. The custom script manually injected shared header markup, copied assets, and decided output files. Astro now owns the page, layout, component, route, and static HTML generation work.[4][5]

Old:
HTML files + scripts/build.mjs -> dist

New:
Astro pages/layouts/components + public assets -> dist
then scripts/postbuild.mjs copies _worker.js and docs/diagrams

What Astro Does Not Replace

Astro replaced the custom page/header build step. It did not replace Cloudflare Pages, Cloudflare Access, _worker.js, D1, or the server-side protection and logging model.

src/components/SiteHeader.astro
  replaces hand-built header injection

src/layouts/SiteLayout.astro
  replaces repeated page shell

src/pages/**/*.astro
  replaces standalone HTML page files

astro build
  replaces most of scripts/build.mjs
Memory Line

Current project: plain HTML is still correct. If it grows, move to Astro first. React is for heavier interactive surfaces. Next is for a full React application with server-side product needs.

Reference branch: syd-prop-deciding-framework

References

  1. Sydney Property Project GitHub repository: source repository for the project.
  2. Sydney Property Guide live site: Cloudflare Pages site for the project.
  3. Project reference branch: syd-prop-deciding-framework: frozen branch at commit 87412b3 for comparing this decision against the current project state.
  4. Shared header template branch: shared-header-template: concrete branch showing the small scripts/build.mjs approach for generating common header markup without migrating to Astro.
  5. Astro docs: Why Astro?: describes Astro as content-driven, server-first, fast by default, and using islands for selective interactivity.
  6. React docs: Learn React: official React documentation for building user interfaces from components.
  7. Next.js docs: official documentation describing Next.js as a React framework with routing, rendering, and full-stack application features.
  8. Cloudflare Pages docs: Cloudflare Pages is the static hosting target already used by the current project.