24 — Static Site Generators — Render Once, Serve Forever

"Just uploading HTML files" was how I wrote off static site generators, which hid the interesting half of the story. The one sentence that separated them: render once, at build time, then serve plain files. Once I had that frame, the whole category made sense — and so did the trade-off it's built around.

There are really only three moments a page's HTML can come into existence, and SSG picks the third:

The thing I had to see clearly is when the work happens. With CSR the browser does the rendering, every time, after shipping a mostly-empty page and a JavaScript bundle. With SSR the server does the rendering, every request, which is correct but means a machine is on the clock for every visitor. SSG refuses both — it does the rendering once, when content or code changes, and hands the result off as flat HTML that a CDN (content delivery network — servers spread around the world) can copy to the edge (the server nearest each user) and serve with no computation at all [1]. Visitors never touch the build; they touch a file.

The trade-off, stated plainly

SSG front-loads the cost. The build re-runs only when content or code changes — a new blog post, a deploy, a content edit — and the output is a set of static .html files plus assets. Between builds, nothing computes. That gives you four properties that follow directly from "it's just files" [1][2]:

• Fast — the server returns a pre-built file; there's no template rendering on the hot path (the code that runs on every request), and a CDN serves it from wherever's nearest the user.
• Cheap — static files need no always-on application server. Free or near-free hosting is the norm.
• Secure — there's no running process, database, or template engine to attack at request time. The attack surface shrinks to the file server.
• Cacheable — identical bytes for every visitor cache perfectly at every layer (browser, CDN, origin).

The cost you pay is the flip side: content only updates when you rebuild. A page that must reflect per-user, real-time, or frequently-changing data is a poor fit — you'd rebuild constantly, or fake freshness with client-side fetches, which is really CSR bolted onto an SSG shell. SSG wins when content changes infrequently relative to reads [1]. That's why the canonical SSG use cases are all read-heavy, update-rare: blogs, documentation, marketing sites, landing pages.

Astro — zero JS by default, islands when you need it

Astro is the SSG I kept hearing about, and its angle is a single design decision: ship zero JavaScript by default [3]. Components (React, Vue, Svelte, or Astro's own) render to static HTML at build time, and the JS that made them interactive is dropped on the floor unless you explicitly opt in.

The opt-in mechanism is partial hydration, or "islands" [3]. You mark a component as an interactive island — a search box, a carousel, a like button — and only that component ships its JavaScript. Everything around it stays as inert HTML. So a 50-component marketing page with one interactive form ships the form's JS and nothing else. The mental shift for me: the page isn't "a React app"; it's HTML, with a few tiny apps embedded where interaction is actually needed.

Astro also gives file-based routing and first-class markdown/mds support, which is exactly what a content site wants — but the islands idea is the part worth remembering. It's SSG's "render once, serve files" principle applied inside the page itself.

SvelteKit — SSG as one mode among several

SvelteKit is a full-stack framework on top of Svelte, and it treats SSG not as its identity but as one rendering mode you can flip on [4]. A SvelteKit app can be SSR, SSG, or a mix, configured per page with a single adapter and page option. The same codebase, different output: prerender a marketing page to static HTML at build, SSR a dashboard at request time, CSR a tiny widget. The framework picks per route.

This is the pattern that made SSG click for me as a strategy rather than a product. Astro is an SSG. SvelteKit has an SSG mode. Next.js, Nuxt, and Remix sit in the same camp — they're hybrid renderers that can emit static output where it pays off and fall back to server or client rendering where it doesn't [2]. The build-time-vs-request-time choice isn't global; it's per page.

The Svelte half matters too. Svelte is a compile-time framework — it turns components into optimized vanilla JS (plain, framework-free JavaScript) at build time, with no virtual DOM (no in-memory draft of the page) and a tiny runtime (very little framework code shipped to the browser) [5]. That pairs naturally with SSG: if you're already compiling away the framework at build time, prerendering the whole page to static HTML is the same idea taken one step further. The bundle you ship is small, and the page is already HTML before deploy.

react-router — client routing, not a renderer

The roadmap groups react-router under this node, and the thing I had to untangle is that react-router isn't an SSG at all — it's a client-side router [6]. It solves a different problem: once a React app is in the browser, how does it change "pages" without a full reload? react-router manages the URL, swaps the view, handles lazy loading (loading a route's code only when it's visited) and route guards (checks that block a route unless a condition is met), and turns a single-page app into something that feels like a multi-page site.

Why it sits next to SSGs: in an SSG output, or any static deployment, there's no server to handle routes — every URL has to resolve to a static file. react-router is the client-side answer to "how do I have many logical routes backed by a static bundle." The two ideas compose: SSG produces the initial HTML cheaply; react-router (or a framework's built-in router) takes over navigation in the browser afterward. Modern react-router also supports data loading and framework-style modes, but at its core it's the navigation layer, and a static file can be the entry point it loads.

How I use this

The habit these notes left me with is one question before I reach for a framework: how often does this content change, relative to how often it's read? If reads vastly outnumber updates — a blog, docs, a portfolio — SSG is almost always right: build once, serve from a CDN, sleep well. If every request needs fresh or per-user data, SSG is the wrong tool and SSR or CSR is honest about it. And if most of the page is static but a corner needs life, that corner is an island, not a reason to ship a full app.

That single ratio — update frequency to read frequency — is the whole decision. Everything else (Astro vs SvelteKit, islands vs hybrid, which router) is implementation once the rendering moment is settled.

References

[1] Cloudflare, "What is a static site generator?," Cloudflare Learning Center, 2024. [Online]. Available: https://www.cloudflare.com/learning/performance/static-site-generator/

[2] The New Stack, "Get back to basics with static website generators," 2023. [Online]. Available: https://thenewstack.io/get-back-to-basics-static-website-generators/

[3] Astro, "Astro — The web framework for content-driven websites," 2024. [Online]. Available: https://astro.build/

[4] Svelte, "SvelteKit documentation," 2024. [Online]. Available: https://kit.svelte.dev/docs/introduction

[5] The New Stack, "All about Svelte, the much-loved, state-driven web framework," 2023. [Online]. Available: https://thenewstack.io/all-about-svelte-the-much-loved-state-driven-web-framework/

[6] Remix Software, "React Router," 2024. [Online]. Available: https://reactrouter.com/