Module 1: Why Astro

Most web frameworks are built around the assumption that your site needs to do a lot at runtime. React, Vue, Next.js — they were designed to handle complex interactivity, state management, and dynamic data. That’s fine if you’re building an application. But most of what people actually want to build is not an application.

A personal site. A newsletter landing page. A product documentation hub. A blog. A course platform. A portfolio. These are content sites — and for content sites, shipping JavaScript to every visitor is a choice you’re making, not a requirement imposed on you.

Astro is built on a different assumption: most pages should be HTML, and JavaScript should be opt-in.

What Astro Actually Does

Astro is a static site generator that lets you write components using a syntax that looks familiar if you’ve used React or Vue, then compiles everything down to plain HTML at build time. The result is fast by default — there’s no client-side framework to boot, no hydration delay, no bundle to download.

What makes it interesting for AI-assisted development is the component model. You write .astro files that mix HTML, CSS, and JavaScript in a way that’s close enough to the web platform that Claude Code can read and generate them fluently. It’s not an abstraction that creates a translation problem — it maps directly to how the web works.

I’ve built eight sites with Astro over the past year or so:

• jimchristian.net — personal site, deployed to IONOS VPS via rsync
• signalovernoise.at — the Signal Over Noise public site
• members.signalovernoise.at — this platform you’re reading right now
• sbc.jimchristian.net — Second Brain Chronicles blog
• definitelyrealproducts.com — a comedy product site
• thinklikeacoder.org — a book companion site
• howtocodeinminecraft.com — an educational site
• sketchscript.app — a tool landing page

They’re different in purpose, audience, and complexity. They all use Astro. They all build in under 30 seconds. They all score well on Core Web Vitals. That’s not because I’m particularly clever — it’s because the framework makes the right thing easy.

The Content Site Sweet Spot

Astro shines when:

• Your content is mostly text and images
• Pages don’t change based on who’s logged in (or only a small part does)
• You want the site to be fast without doing performance archaeology
• You want to write content in Markdown and have it just work
• You’re deploying to a CDN, static host, or VPS

It’s less suited to:

• Complex real-time features (live chat, collaborative editing, streaming data)
• Applications where every page is highly personalised at request time
• Projects where you need server-side rendering for every request

The members platform here is an edge case — it serves mostly static content with a thin layer of client-side auth to gate access. That works fine. But if I were building a fully dynamic application with database queries on every page load, I’d reach for something else.

Why It Works Well With Claude Code

The honest reason I’ve built everything in Astro for the past year is that Claude Code is very good at it.

A few reasons:

The file structure is predictable. Pages live in src/pages/. Layouts in src/layouts/. Components in src/components/. Content in src/content/. Claude Code can navigate this without guidance.

The syntax is familiar without being framework-specific. Astro components look like HTML with a script block at the top. Claude Code doesn’t have to translate between a mental model and a runtime — what you see is close to what ships.

The abstraction is low. When something breaks, the cause is usually visible. There’s no deep runtime magic to debug. That makes AI-assisted debugging more effective — Claude Code can actually trace what’s wrong rather than guessing at framework internals.

Markdown just works. Astro’s content collections let you write in Markdown with typed frontmatter. Claude Code can draft content, update frontmatter, and create new pages without needing to understand a CMS API.

Static vs Dynamic: The Decision

Before you start building, decide where your content lives on the static/dynamic spectrum.

Fully static: Every page is generated at build time. Fast, cheap to host, trivial to cache. Right for most content sites.

Hybrid: Most pages are static, but a few use server-side rendering for dynamic data. Astro supports this with output: 'hybrid' in config. Right for sites with occasional dynamic needs.

Server: Every page is rendered on request. You lose the CDN caching benefits but gain full server-side logic. Right for applications, not content sites.

Start static. You can add dynamism later. The opposite is much harder.

---

Module 2 gets into the actual scaffold. But before you move on: check that you have Node.js 18 or later installed (node --version), and that you’re comfortable opening a terminal. That’s all you need.