The Mental Model
What Astro actually is — a compiler, not a server. The single concept that makes everything else click.
Astro Is a Compiler
Astro is not a web server. It’s a compiler — like LaTeX or a C compiler. You feed it source files, it outputs finished HTML.
LaTeX: .tex files → pdflatex → .pdf files you distribute
Astro: .astro + .md files → astro build → .html + .css files you upload
The output (dist/ folder) is a pile of static files. No Python process running, no database, no server-side logic. Cloudflare (or any host) just serves files — like putting PDFs on a file server.
What “Static Site Generator” Means
The term is literal:
- Static — the output is fixed HTML files, not dynamically generated per request
- Site — a collection of web pages
- Generator — a program that produces them from source templates
When someone visits krowdev.pages.dev/article/welcome-to-krowdev/, Cloudflare finds dist/article/welcome-to-krowdev/index.html and sends it. No code runs. It’s as fast as file serving can be.
The Two Phases
Everything in Astro happens in one of two phases:
| Phase | When | Where | What Runs |
|---|---|---|---|
| Build time | When you run npm run build | Your machine or CI | All your Astro/TS code, markdown processing, image optimization |
| Runtime | When someone visits the site | User’s browser | Only explicit <script> tags (if any) |
By default, Astro ships zero JavaScript to the browser. Your code runs once at build time and produces pure HTML. The only JS on krowdev right now is the 15-line theme toggle.
This is the opposite of React/Next.js, where a JavaScript application runs in the browser. With Astro, the browser just renders HTML — like opening a .html file from your desktop.
Build Time Is Your Superpower
Because code runs at build time, you can do expensive things for free:
- Query every markdown file and sort them by date? Free — happens once during build
- Validate every article’s frontmatter against a schema? Free — happens at build time
- Optimize images and compress fonts? Free — done during build
- Generate a search index for every page? Free — Pagefind runs post-build
None of this costs anything at runtime. Your visitors get pre-computed results.
Think of it like precomputing a lookup table vs. calculating on the fly. Astro precomputes everything into HTML so there’s nothing left to compute when someone visits.
Challenge: Verify the mental model
Open the krowdev project and run:
cd sitenpm run buildNow look at the output:
ls dist/ls dist/guide/agentic-coding-getting-started/cat dist/guide/agentic-coding-getting-started/index.html | head -5Confirm: the output is just .html files. No .js bundles (except the tiny theme toggle), no server code. This is what gets uploaded to Cloudflare.
What about dynamic features like search?
Pagefind builds a search index at build time — a compressed data file. The search UI loads this index in the browser and searches client-side. No server needed. This is the “precompute everything” pattern taken to its logical end.