Astro: HTML First, JavaScript When You Need It  🔗 **Source:** [Astro: HTML First, JavaScript When You Need It](https://jadjoubran.io/blog/why-we-chose-astro?_bhlid=5de61afc52908d6a2e4e717e4204292bb18e16c3) > [!note]+ Document Notes > tags: [astro-framework, progressive-enhancement, web-standards, developer-education, javascript-frameworks] > author: Jad Joubran > source: jadjoubran.io > reference: https://jadjoubran.io/blog/why-we-chose-astro > date created: {{date:YYYY-MM-DD}} {{time:HH:mm}} > > # 🏷️ Title: Astro: HTML first, JavaScript when you need it > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ## 📝 Summary - Jad Joubran, a developer and educator, explains why he and Cyd Stumpel picked Astro as the teaching tool for the API module of the Web Design & Development minor at the Amsterdam University of Applied Sciences (HvA), a four-week sprint covering both Content APIs (CMS/service data) and Web APIs (browser-native APIs like geolocation and View Transitions). - The choice mattered because the students are designers who are fluent in HTML/CSS but still building JavaScript fluency, and the minor's stated values are web standards, progressive enhancement, accessibility, and performance. A framework that forces a component model, a build step, and a hydration mental model before a student can render a list of blog posts spends the student's attention on the tool instead of the web. - Key stakeholders: the students (creative designers learning to consume APIs), the minor's teaching staff (Joubran and Cyd Stumpel, an award-winning creative developer who originally proposed Astro), and by extension any developer or educator choosing a stack for a content-driven project. - Risks and tradeoffs: the article is a single practitioner's account, not a controlled comparison — there's no data on learning outcomes versus a React- or Vue-first curriculum, and the piece doesn't address Astro's own learning curve at scale (e.g., content collections, adapters for different deployment targets, or the added complexity once islands and multiple UI frameworks are mixed in one project). The framing is also self-selecting: a tool praised for "getting out of the way" is being evaluated by people who chose it precisely because it stays out of the way. - Bottom line: Astro's frontmatter model (server-executed code above a plain-HTML template) lets students learn to fetch and render data using real platform primitives (`fetch`, `Response`) instead of framework-specific state machinery, and its zero-JavaScript-by-default architecture makes progressive enhancement the path of least resistance rather than an opt-in discipline. ## 📖 Main Content - **The core problem being solved**: teaching API consumption to designers usually front-loads tooling (bundlers, client-side fetch, loading-state management) before the actual lesson — "here's an API and here's how you put it on the page" — can happen. Joubran frames this as a tooling detour that buries the pedagogical goal. - **Why Astro fits the constraint**: the students' strength is HTML/CSS; JavaScript is their "growth edge." A tool that requires a component model, JSX, and a hydration mental model before rendering anything spends their limited attention budget on the framework rather than the web platform. Astro's `.astro` files are described as "HTML that you sprinkle logic into" — no component model prerequisite, no JSX, no `return` wrapping markup. - **The frontmatter model**: the block between two `---` fences runs on the server (or at build time); the markup below it renders to HTML. Students write data-fetching in the fence and loop over results in the template — no `useEffect`, no `isLoading` state, no client-side round trip. Joubran, who started with PHP 13+ years ago, frames this as the same "fetch on the server, render finished HTML" experience he learned the web with, modernized for the JavaScript era. - **Platform over framework**: because `fetch` and `Response` are used directly (not wrapped in a framework's data layer), the course teaches web standards that outlast any specific framework. The same applies to Web APIs — the geolocation example uses a server-rendered `<button>` progressively enhanced by a plain `<script>` calling `navigator.geolocation` and `addEventListener`, i.e., the actual browser platform, not an abstraction over it. - **Progressive enhancement as the default, not an opt-in**: Astro ships zero JavaScript unless the author adds it, either via a plain `<script>` tag or an "island" (a component that hydrates independently while the rest of the page stays static HTML). Reusable `.astro` components take props with no framework required at all; a framework (React, Vue, Svelte, Preact, Lit) is added later, only on the specific island that needs it, as an official integration. Joubran links this directly to Cyd Stumpel's own writing on why the minor teaches progressive enhancement, arguing Astro makes the pedagogically "right thing" the path of least resistance. - **Performance as an emergent property**: the zero-JS baseline, scoped/bundled CSS, built-in `<Image>` optimization, opt-in prefetching, and the islands model (isolating heavy interactive widgets from the rest of the page) combine so that a student's first Astro site tends to have solid Core Web Vitals without deliberate performance engineering. - **Scaling across the whole course**: Astro covers static pages, server-side rendering, and API endpoints with one tool. The secret-key example (a server endpoint that fetches from an authenticated Content API and returns a `Response` with `Content-Type: application/json`) shows students handling credentials safely without leaving Astro or learning a second stack, while reinforcing the same `Response` primitive from earlier in the course. - **Terms defined in context**: "frontmatter" (the fenced server/build-time code block at the top of an `.astro` file), "island" (an independently hydrated interactive component embedded in an otherwise static page), "progressive enhancement" (building a working baseline first, then layering JavaScript-driven enhancement on top rather than requiring JavaScript for basic function). - **Uncertainties/contested claims**: the article doesn't cite any measured learning outcomes, retention data, or comparison cohort — the argument is experiential/pedagogical, backed by Joubran's and Stumpel's professional judgment rather than a study. It also doesn't address Astro-specific rough edges (e.g., configuring integrations, content collections, or deploying SSR vs. static output) that a four-week sprint might or might not surface. ### 🗒️ Notes - Course context: four-week sprint inside the Web Design & Development minor at HvA (part of the broader "Everything Web" program), covering Content APIs and Web APIs side by side. - Cyd Stumpel, an award-winning creative developer who lectures in the minor, originally suggested Astro; Joubran credits her with the "nudge." - The one-line pitch that sold the team: "Astro is just HTML, and JavaScript is the part you add when you need it." - Code example 1 (basic `.astro` file): a frontmatter `const title = "My first Astro page";` followed by `<h1>{title}</h1>` — illustrates the "HTML with a sprinkle of logic" framing, contrasted against React's prerequisite component-model tax (props, state, a render function). - Code example 2 (server-side fetch): frontmatter fetches `https://jsonplaceholder.typicode.com/users`, awaits `.json()`, then the template maps over `users` to render a `<ul>` of mailto links — no `useEffect`, no loading state, no client round-trip. - Code example 3 (Web API / progressive enhancement): a server-rendered `<button id="locate">` and `<p id="result">` enhanced by a plain `<script>` that queries the DOM, attaches a click listener, and calls `navigator.geolocation.getCurrentPosition`. - Code example 4 (reusable component without a framework): `UserCard.astro` takes `Astro.props` (`name`, `email`) and renders an `<li>` — imported and reused like any other tag, demonstrating componentization before any client-side framework is introduced. - Code example 5 (secret-key API endpoint): `src/pages/api/articles.js` exports a `GET()` function that fetches an external API with a `Bearer` token from `import.meta.env.API_KEY`, then returns `new Response(JSON.stringify(articles), { headers: { "Content-Type": "application/json" } })` — keeps the key server-side, returns clean JSON, and reuses the `Response` primitive taught earlier. - Performance defaults listed: zero-JS baseline, scoped/bundled CSS, built-in image optimization via `<Image>`, opt-in prefetching, and the islands model isolating heavy widgets. - Explicit "what we want students to walk away with": forgetting the word "Astro" is fine; forgetting "HTML first, fetch the data, render it, and add JavaScript only where it earns its place" is not. - The article closes with an open invitation for other educators to share their own stack choices and reasoning — signals this is part of an ongoing public conversation, not a one-off announcement. ## 📚 References - [Astro](https://astro.build/) — the framework at the center of the article. - [Web Design & Development minor / Everything Web](https://everythingweb.org/) — the program the API module belongs to. - [Amsterdam University of Applied Sciences (HvA)](https://www.amsterdamuas.com/) — the institution offering the minor. - [Cyd Stumpel](https://cydstumpel.nl/) — award-winning creative developer, lecturer, and the person who suggested Astro. - [Why we teach our students progressive enhancement](https://cydstumpel.nl/why-we-teach-our-students-progressive-enhancement/) — Cyd Stumpel's companion piece on the pedagogical rationale referenced directly in the article. - [JSONPlaceholder](https://jsonplaceholder.typicode.com/) — the demo API used in the code examples (referenced, not explicitly hyperlinked in the article). - [Declarative Partial Updates unlock a new Native Component Model](https://jadjoubran.io/blog/declarative-partial-updates) — related post by the same author, listed under "See also." - [9 Times the Web Platform Was Influenced by Libraries](https://jadjoubran.io/blog/web-platform-influenced-by-libraries) — related post, "See also." - [Working with Dates in JavaScript Using the Temporal API](https://jadjoubran.io/blog/javascript-temporal-api) — related post, "See also." - [Why we chose Astro (original article)](https://jadjoubran.io/blog/why-we-chose-astro) — primary source for this analysis. ## 🗣️ Paraphrase - Paragraph A: When you teach designers to work with APIs, the standard path buries the actual lesson under setup — bundlers, client-side fetch logic, loading states — before anyone has seen real data land on a page. Joubran and his co-lecturer needed a tool that gets a designer from "I have an API" to "it's on the page" without that detour, because their students are already strong in HTML/CSS and still building JavaScript confidence. Any tool that demanded a component model or a hydration mental model up front would spend the students' attention on the framework instead of the web itself — and the course explicitly wants that attention going toward web standards, progressive enhancement, accessibility, and performance. - Paragraph B: Astro fit because its `.astro` files are just HTML with a small amount of server-executed logic sitting above the markup — fetch calls happen in that server-run "frontmatter," and the browser only ever receives finished HTML, with no loading spinners or client-side data machinery to teach. Because Astro ships zero JavaScript unless you explicitly add it (via a script tag or an "island"), progressive enhancement isn't something students have to remember to opt into — it's the default they'd have to work against. The same approach scales across the whole course, from static pages to server-side rendering to secret-key-protected API endpoints, so students never have to switch stacks as their skills grow, and the underlying platform knowledge (`fetch`, `Response`, browser APIs) outlasts whatever framework is fashionable later. ## 📰 Newsletter Astro just picked up an unusually good endorsement: a university-level web design program built its entire "teach students to consume APIs" module around it, specifically because it stays out of the way. If you build with WordPress and have been eyeing headless setups or a static front end for content-heavy sites, the pitch is worth ten minutes of your time — Astro's frontmatter pattern (fetch your data server-side, loop over it in plain HTML) is close in spirit to how a block theme template or a PHP template file already works, minus the client-side JavaScript tax that a lot of headless-WordPress tutorials assume you need. The zero-JavaScript-by-default "islands" model is also a handy mental model for anyone maintaining a WordPress site full of third-party embeds and widgets: isolate the interactive bits, keep the rest of the page as plain, fast HTML. Worth a read if you're evaluating a companion static/headless layer for a WordPress project, or just want a clean explanation of "progressive enhancement" you can hand to a junior dev. ## ✅ Action Items #### DevRel - Developer advocacy: if presenting Astro or similar HTML-first tools to a WordPress-adjacent audience, borrow Joubran's framing directly — lead with "here's the API on the page" before any tooling setup, rather than starting with configuration. - Education: the frontmatter-as-server-code mental model (fetch above the fence, render below it) is a strong analogy for explaining server-rendered PHP templates to JavaScript-first developers, and vice versa for explaining Astro to PHP-first developers. - Developer experience: none surfaced directly — the article doesn't discuss docs, SDKs, or onboarding friction beyond the teaching context. - Developer marketing: not applicable — this is a first-person educational account, not a campaign or funnel. - Community management: not applicable — no moderation or code-of-conduct content in this source. - Internal/external/cross-project: the explicit invitation at the end ("if you teach this stuff too... I'd genuinely like to hear them") is a low-friction cross-project feedback loop worth modeling for other technical blogs. #### OSPO - Policy & Governance: not applicable to this source — no contribution policy or charter discussion. - License Compliance: not applicable — Astro's license isn't discussed in the article. - Security Management: the secret-key API endpoint pattern (server-side `Bearer` token, never exposed to the browser) is a concrete, teachable security default worth citing when writing secure-by-default guidance for junior developers. - Software Inventory: not applicable to this source. - Developer Support: not applicable to this source. - Community Engagement: not applicable to this source. - Strategic Alignment: the article is itself a good case study in choosing tooling because it reinforces stated values (web standards, accessibility, performance) rather than because it's trending — useful to cite when justifying a tool-selection decision to stakeholders. #### Community - Maintainers: not applicable — no maintainer-facing content in this source. - Contributors: not applicable — no contribution-path content in this source. - Sponsors: not applicable — no sponsorship content in this source. - Ecosystem: Astro's "start with no framework, add React/Vue/Svelte/Preact/Lit only on the island that needs it" model is a useful reference point for any ecosystem debate about "pick one framework" vs. "interop across frameworks." #### WordPress - Core: not applicable — the article doesn't touch WordPress core. - Core Performance: the zero-JS-by-default + scoped CSS + built-in image optimization stack is a useful performance-budget reference when discussing what "fast by default" should look like for WordPress block themes. - Core AI: not applicable to this source. - Core Program Team: not applicable to this source. - Mobile: not applicable to this source. - Playground: not applicable to this source. - Community: not applicable to this source. - Training: the four-week "Content APIs + Web APIs" curriculum structure is a reusable shape for a WordPress-adjacent training module on consuming the REST API without a heavy client-side framework. - Marketing: not applicable to this source. - Support: not applicable to this source. - Design: not applicable to this source. - Documentation: the frontmatter/server-fetch example is a good "before you reach for React" reference to link from WordPress REST API documentation aimed at designers learning to fetch data. - Photos: not applicable to this source. - TV: not applicable to this source. - Polyglots: not applicable to this source. - Accessibility: progressive enhancement as a *default* rather than an opt-in is directly relevant to WordPress accessibility guidance — worth citing alongside WCAG 2.2 AA material. - Meta: not applicable to this source. - CLI: not applicable to this source. - Hosting: not applicable to this source. - Tide: not applicable to this source. - Openverse: not applicable to this source. - Themes: not applicable to this source. - Plugins: not applicable to this source. #### The WPCC - Programs, Projects, Funding experiments: not applicable to this source — the article contains no WPCC-relevant governance or funding content. ### FAIR - Not applicable to this source — no FAIR-program content (technical independence, funding covenants, or governance artifacts) appears in this article. ## 🧪 Hypotheses - H1: Students taught data-fetching via Astro's server-executed frontmatter will demonstrate stronger transfer of the underlying `fetch`/`Response` concepts to non-Astro contexts (e.g., a Node script or a different framework) than students taught the same concept via a client-side `useEffect` pattern. - H2: A curriculum with a zero-JavaScript-by-default baseline produces measurably fewer accessibility regressions in student projects (e.g., missing keyboard handlers, broken screen-reader flows) than a curriculum that starts with a client-side-rendered framework. - H3: Students who build their first interactive feature as a progressively-enhanced `<script>` on top of server-rendered HTML will report higher confidence using native browser APIs (geolocation, `addEventListener`) than students whose first interactive feature is built inside a framework's synthetic event system. - H4: Introducing a UI framework (React/Vue/Svelte) only on isolated "islands," after students have already built static and server-rendered pages, reduces the rate of "cargo-culted" framework code (patterns copied without understanding) compared to introducing the framework from day one. - H5: Teaching secret-key handling via a same-stack server endpoint (rather than a separate backend service) increases the number of students who correctly avoid exposing API keys in client-side code in a follow-up assessment. ### 📊 Methodology - For H1/H3: a controlled A/B cohort study across two parallel sections of the same minor (or two consecutive cohorts), one taught with Astro's server-first pattern and one with a client-first framework, followed by a transfer task in a third, unfamiliar tool — score correctness and time-to-completion. - For H2: an accessibility audit (automated + manual keyboard/screen-reader pass) of final student projects across cohorts, using a fixed rubric (e.g., WCAG 2.2 AA success criteria) scored by an auditor blind to which tool was used. - For H4: static analysis of student repositories for framework-idiom patterns used without corresponding explanation in code comments or accompanying documentation, compared across cohorts. - For H5: a short written or practical assessment after the API-endpoints unit asking students to design a feature requiring a secret key, scored on whether the key ever appears in client-shipped code. ### ❓ Questions - Does the "forget Astro, remember the platform" outcome actually hold a year later, or does tool-specific muscle memory (Astro-specific syntax, file conventions) persist longer than the platform concepts it's meant to be a vehicle for? - How does the islands model hold up once a project needs multiple interactive components that share state across island boundaries — does the "start with no framework" simplicity survive that complexity, or does it just defer the framework decision? - What does the failure mode look like for a student who never needs to add JavaScript at all during the course — do they leave with a real understanding of *why* progressive enhancement matters, or just a syntax pattern they never had to break? - Would the same pedagogical benefits hold with a different HTML-first, server-rendered tool (e.g., htmx-plus-any-backend, or a Rails/Django/Laravel templating layer), or is something specific to Astro's JS-ecosystem positioning doing the work? ### 🔮 Future Research - A longitudinal follow-up on HvA minor alumni to see whether the "platform over framework" retention claim holds once they're working with whatever framework their first job uses. - A comparative case study against other design-and-code programs that deliberately chose a client-first framework (React, Vue) for the same age/skill cohort, matched on accessibility and performance outcomes rather than student satisfaction alone. - Documentation of common student failure modes specific to Astro (e.g., confusing frontmatter scope, misunderstanding when an island hydrates) to see whether Astro introduces its own new "framework tax" once the sprint moves past the basics. ### 💡 Implications - **Practice**: teams choosing a stack for a content-driven marketing site or documentation project have a credible, values-driven (not just hype-driven) reason to default to Astro over a full SPA framework, particularly when the team's strengths lean toward HTML/CSS/content rather than JavaScript engineering. - **Policy/curriculum design**: the article models a decision-making pattern worth generalizing beyond Astro — asking "does this tool reinforce or fight our stated pedagogical values?" before "what does the industry use?" is a reusable heuristic for any curriculum committee picking a primary teaching stack. - **Security**: the same-stack secret-key endpoint pattern is a low-friction way to teach secure-by-default credential handling without introducing a second backend service or a separate security lecture. - **Education**: sequencing "static HTML first, then server-fetched data, then progressive JS enhancement, then optional framework islands" is a concrete syllabus scaffold other programs could adopt directly, regardless of which specific tool they use. - **Funding models**: not directly addressed by the article — no discussion of cost, licensing, or hosting budget implications of the Astro choice. ### 🧠 Learning Styles Assessment - Reading level estimate: approximately Flesch-Kincaid Grade 9-10 (Flesch Reading Ease roughly mid-50s) — the prose is conversational and uses contractions and short sentences, but technical vocabulary (frontmatter, hydration, islands, `Response` objects) and multi-clause reasoning about tradeoffs push it above a general-audience reading level. Estimate only; not computed with a scoring tool. #### 👀 Visual learners - Present: one screenshot of the Astro landing page; five fenced code blocks showing concrete before/after contrasts (plain HTML vs. React's component tax, client fetch vs. server fetch). - Improve: a side-by-side diagram of the request lifecycle (client-fetch model vs. Astro's server-fetch model) would make the "no client round-trip" claim more immediately visible than prose alone; an annotated diagram of the islands architecture (which parts of the page hydrate vs. stay static) would also help. #### 🔊 Aural learners - Present: none — no audio version, podcast, or narration accompanies the article. - Improve: a short (2-5 minute) audio walkthrough of the frontmatter/islands mental model, or speaker notes suitable for reading aloud in a lecture, would extend this beyond a purely visual medium. #### 🗣️ Verbal learners - Present: strong use of analogy and plain-language reframing throughout — "fetching data stops being 'set up a whole client-side machine' and becomes 'call fetch, loop over the result, write the HTML'" is a definition-by-contrast that verbal learners respond well to; the PHP-to-Astro comparison is another such analogy. - Improve: a short glossary of the article's key terms (frontmatter, island, hydration, progressive enhancement) collected in one place would help readers unfamiliar with any one of them. #### 🧩 Kinesthetic learners - Present: five runnable code snippets that a reader could paste into a real Astro project and execute directly. - Improve: no linked sandbox, REPL, or step-by-step "build this" exercise is provided — a linked StackBlitz/CodeSandbox reproduction of each example would let readers experiment immediately rather than only read the code. #### 🧠 Logical learners - Present: the article is structured as a chain of constraints leading to a conclusion (student skill profile → curriculum values → tool requirements → Astro as the fit), which logical learners tend to track well. - Improve: an explicit decision matrix or table (criteria: component-model prerequisite, JS-by-default, performance defaults, scaling range — scored across Astro, React, Vue, plain HTML) would make the comparative reasoning more scannable than the current prose-only argument. #### 🧑‍🤝‍🧑 Social learners - Present: the closing line explicitly invites reader response ("if you've made a different call and have reasons, I'd genuinely like to hear them") and credits a named collaborator (Cyd Stumpel) throughout. - Improve: an embedded comment thread or a linked discussion (e.g., a specific forum or social post) would give social learners a concrete place to engage rather than an open-ended invitation with no stated venue. #### 🧘‍♀️ Solitary learners - Present: the article is self-contained and can be read and absorbed without any group activity. - Improve: a short self-check ("could you explain to a classmate why this page has zero JavaScript by default?") at the end would give solitary learners a way to verify their own understanding. #### 🌿 Naturalistic learners - Present: the "grows with the student" framing (the same tool serving a first static page and, a year later, a developer's interactive island) has a loose ecosystem/growth metaphor. - Improve: an explicit lifecycle framing (e.g., comparing a project's JavaScript footprint growing only as its actual needs grow, versus front-loading a large dependency tree regardless of need) would sharpen this into a genuine sustainability/impact angle — relevant given the real energy cost of shipping unnecessary client-side JavaScript at scale. ### 📊 Accessibility Assessment #### Screen reader semantics - Present: the article's own code examples use semantic HTML (`<button>`, `<ul>`, `<li>`, `<a href="mailto:...">`) rather than generic `<div>`-based markup, modeling good practice. - Improve: the article itself doesn't discuss ARIA roles, landmarks, or alt text explicitly — it demonstrates good defaults through example rather than stating the accessibility rationale directly. #### Keyboard navigation - Present: because Astro's default output is plain server-rendered HTML (real `<button>` elements, real links), keyboard operability is inherited "for free" rather than requiring custom focus management. - Improve: the geolocation example doesn't address what happens for a keyboard-only or screen-reader user who can't grant/receive geolocation feedback visually — the `result.textContent` update should be paired with an ARIA live region so assistive tech announces the change, which the article doesn't mention. #### Contrast and readability - Present: not assessed — this is a code/prose article, not a UI design the article's own site can be scored against without a separate site audit. - Improve: not applicable to the article's content itself. #### Text resizing and reflow - Present: not assessed — no layout or CSS content in the article's own reasoning. - Improve: not applicable to the article's content itself. #### Media and captions - Present: one screenshot with descriptive alt text noted in the fetched content ("Screenshot of the Astro landing page at astro.build"). - Improve: no other media (video, audio) is present to require captioning. #### Forms and interactions - Present: the "Find me" button example is a simple, low-risk interaction with clear labeling. - Improve: as noted above, the result announcement after a geolocation click should use an ARIA live region (e.g., `aria-live="polite"` on the `#result` element) so the update is accessible to screen-reader users — a good real-world addition the article's own example is missing. #### Standards reference - Gaps map loosely to WCAG 2.2 success criterion 4.1.3 (Status Messages) for the un-announced geolocation result update; the rest of the article's code examples are broadly aligned with semantic-HTML best practice (relevant to 1.3.1 Info and Relationships, 2.1.1 Keyboard) by virtue of Astro's server-rendered defaults. ### 🌍 DEIB Assessment #### Cultural breadth - Present: the context is explicitly Dutch/European higher education (Amsterdam University of Applied Sciences); the article doesn't generalize this as a universal template, which avoids overclaiming. - Improve: no comparison to how this curriculum choice might play out in other educational systems or resource-constrained settings (e.g., programs without reliable broadband, where a build step or SSR hosting requirement could be a bigger barrier than the article accounts for). #### Inclusive language - Present: gender-neutral language throughout ("students," "a designer," "they"); jargon (frontmatter, islands, hydration) is defined in-line rather than assumed. - Improve: none needed — this dimension is well handled for a technical audience. #### Neurodiversity support - Present: consistent structure (constraint → solution → code example, repeated per section) and short paragraphs support predictable, chunked reading. - Improve: a small number of sections (e.g., "Progressive enhancement and islands") pack several distinct ideas into one block; splitting into more, smaller subheadings would aid readers who benefit from more frequent structural anchors. #### Representation - Present: the article credits a named woman collaborator (Cyd Stumpel) prominently and links to her own writing, rather than treating the pedagogical rationale as solely the (male) author's idea. - Improve: no other named contributors or student perspectives are represented — a quote or example from an actual student's experience would balance the instructor-only viewpoint. #### Psychological safety - Present: the tone is collegial and non-defensive; the closing explicitly invites disagreement ("if you've made a different call and have reasons, I'd genuinely like to hear them") rather than framing Astro as the only correct choice. - Improve: none needed — this is a low-stakes technical opinion piece with an already-open, non-adversarial framing. ### ✅ Logical Validity #### Strong reasoning - Constraint-to-conclusion reasoning: the article establishes a clear premise (students are HTML/CSS-strong, JS-building; the program values web standards, progressive enhancement, accessibility, performance) and shows, example by example, how Astro's specific mechanics (frontmatter execution model, zero-JS default, islands) satisfy each stated value. This is a coherent inductive argument built from concrete code rather than assertion alone — each claim ("no client round-trip," "zero JavaScript baseline") is backed by a runnable example. - Analogical reasoning: the PHP comparison ("this is how I got to know and understand the web... the same experience, but modernized for the JavaScript era") is an effective analogy grounding an unfamiliar (to some readers) Astro concept in a widely-understood prior model (server-rendered PHP templates), aiding transfer for readers with a server-side background. #### Fallacies - No significant fallacies identified. The article is explicit about the boundary of its own claim (a teaching-context recommendation, not a universal "always use Astro" prescription) and attributes credit rather than claiming sole authorship of the idea. One minor rhetorical soft spot: the claim that Astro students will retain platform knowledge "that outlasts any framework" is asserted rather than evidenced — it's a reasonable hypothesis (see H1 above) but is stated with more confidence than the article's own evidence (which is anecdotal/experiential) supports. This falls short of a fallacy but is worth flagging as an unsupported generalization. #### Tone of voice - Conversational, first-person, and confident without being dismissive of alternatives — e.g., "if you're picking a stack for your next content-driven project, not just a classroom, Astro is worth a serious look before you default to a heavier framework" recommends without insisting. The closing paragraph explicitly solicits dissent, reinforcing a collegial rather than evangelistic register. ### 🛡️ DARVO Analysis Not applicable to this source — DARVO (Deny, Attack, Reverse Victim and Offender) is a framework for analyzing responses to accountability claims in interpersonal or institutional misconduct contexts. This article is a first-person technical/pedagogical opinion piece about a tool choice, with no accusation, denial, or victim/offender dynamic present. ## 🎯 Conclusion - Bottom line: Joubran and Stumpel picked Astro for the HvA Web Design & Development minor's API module because its architecture — server-executed frontmatter, a zero-JavaScript default, and an islands model for optional interactivity — mechanically reinforces the values the curriculum already holds (web standards, progressive enhancement, accessibility, performance) rather than requiring students to learn those values against the grain of the tool. Students fetch data with real `fetch`/`Response` primitives instead of framework-specific state machinery, and progressive enhancement becomes the default behavior instead of a discipline they have to remember to apply. - Practical next steps for readers: if you're evaluating a stack for a content-driven site (marketing pages, documentation, a blog, a small data-backed dashboard) and your team leans HTML/CSS-strong rather than JS-engineering-heavy, read Astro's own docs on the frontmatter model and islands architecture before defaulting to a full SPA framework. For educators, the transferable move isn't "use Astro specifically" — it's auditing any candidate teaching tool against your program's actual stated values before adopting it because it's popular. ## 🔄 Refactor Appendix — Astro: HTML first, JavaScript when you need it > Density: 2–5 Literature atoms (H3), 0–3 Permanent candidates (H4). > Defaults: 3 Literature, 1 Permanent. Resonance filter: if you can't > articulate in one line why a claim matters, drop it. > > Konik claim-header rules: present tense, declarative, ≤10 words when > possible, searchable, unique, mirrors annotation focus if present. > > Atomicity: one declarative sentence per atom. "and"/"also" → split. > > Tag pool: #bmf · #addendum · #xref · #articleseed · #storystem · #share · #aphorisms ### 📚 Literature Atoms (H3) #### [H1] Astro's frontmatter runs on the server, not the client > [!quote] ID:rw_pending_1 > "code in the fence runs on the server, the template below it renders to HTML" **Context & use**: - From the "Server-side fetching in the frontmatter" section, describing the `.astro` file model. - Why this matters: this is the mechanical reason students skip `useEffect`/loading-state boilerplate — the fetch happens before the browser ever sees the page. **Tags**: #xref **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H2] Astro ships zero JavaScript unless you add it > [!quote] ID:rw_pending_2 > "you don't opt into progressive enhancement; you'd have to opt out" **Context & use**: - From "Progressive enhancement and islands," describing Astro's default output. - Why this matters: inverts the usual default — most frameworks require deliberate work to progressively enhance; Astro requires deliberate work to avoid it. **Tags**: #xref #aphorisms **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> #### [H3] Islands let one framework hydrate without adopting it everywhere > [!quote] ID:rw_pending_3 > "a component that hydrates on its own while the rest of the page stays static HTML" **Context & use**: - From the same section, defining the "island" concept. - Why this matters: this is the mechanism that lets a course (or a project) defer the "which JS framework" decision until a specific feature actually needs one. **Tags**: #xref **Highlight**: [view highlight](readwise://pending) <!-- atomicity: 1 idea ✓ --> ### 🧠 Permanent Candidates (H4) #### [P1] Tool choice should reinforce stated values, not just convenience **Claim** (one sentence, Courtney's voice): When picking a tool for a team or a curriculum, I check whether its defaults mechanically reinforce the values I already hold — not just whether it's fast to set up or currently popular. **Evidence pointer**: [[#H1]] [[#H2]] **Scope & conditions**: Holds when the values are explicit and shared (a documented curriculum philosophy, a team's stated engineering principles); breaks down as a heuristic when values are vague or contested, since "reinforces our values" can be argued for almost any tool if the values aren't pinned down first. **Links** (≥1 with annotation): - [[Progressive enhancement]] — because applies-in web development and curriculum design contexts alike <!-- atomicity: 1 idea ✓ --> ### ✏️ Fleeting Queue - [F1] Compare Astro's islands architecture directly against WordPress's block-based editor + Interactivity API for a "server-first, JS-on-demand" cross-ecosystem comparison — https://jadjoubran.io/blog/why-we-chose-astro #xref - [F2] The geolocation example lacks an ARIA live region on the result update — worth a short note/PSA on pairing progressive-enhancement demos with accessible status announcements — #addendum ### → Things 3 (max 2 actions) - [ ] Read Astro's content collections and SSR adapter docs to evaluate it for a real content-driven project, not just the teaching context — astro.build #things <!-- deep-read:sections end --> 📄 **Full text:** [[Full Document Contents/Articles/Astro HTML First, JavaScript When You Need It.md|Astro: HTML First, JavaScript When You Need It by jadjoubran.io]] ## Highlights - The one-line framing that sold it: **Astro is just HTML, and JavaScript is the part you add when you need it.** ([View Highlight](https://read.readwise.io/read/01kxh9e8317vmqy5gsny15wfwv)) - Tags: atom/literature/h1 - For a designer, this is the moment it clicks. Fetching data stops being "set up a whole client-side machine" and becomes "call `fetch`, loop over the result, write the HTML." Which is exactly the mental model we want them to have. ([View Highlight](https://read.readwise.io/read/01kxh9e9e1p7xd4hh4sb83bpj2)) - Tags: atom/literature/h3 - This is the minor's philosophy expressed as a tool. We teach progressive enhancement on purpose. Cyd wrote about exactly [why we teach our students progressive enhancement](https://cydstumpel.nl/why-we-teach-our-students-progressive-enhancement/), and Astro makes the right thing the default thing. You don't opt *into* progressive enhancement; you'd have to opt out. ([View Highlight](https://read.readwise.io/read/01kxh9e8s4fpyyaqfp80xjnhs3)) - Tags: atom/literature/h2 - If a student finishes the minor and forgets the word "Astro," that's fine. What we don't want them to forget is the foundation: HTML first, fetch the data, render it, and add JavaScript only where it earns its place. Those are web-standards fundamentals that outlive any framework, and they're exactly what Astro's defaults teach without us having to nag. ([View Highlight](https://read.readwise.io/read/01kxh9ea0489g7t89xx2daaewf)) - Tags: atom/literature/h4