---
name: web-architecture
description: Choosing how a web app renders and whether to use a framework, decided up front. Claude defaults to client-side rendering and hand-rolled vanilla HTML/JS, which is usually the wrong starting point for content sites and multi-page apps. Use when starting or scaffolding a site or app, deciding how pages render (SSR, SSG, CSR), or about to hand-build routing and state. Covers defaulting to server-rendered HTML for first paint and SEO, reaching for a framework when there are several pages, and not over-engineering a single page.
when_to_use: |
  - Starting, scaffolding, or proposing the structure for a website or web app
  - Deciding how pages render: server-rendered (SSR), static (SSG), or client-rendered (CSR/SPA)
  - The project has several pages, shared layout, routing, or data fetching, raise a framework even if the user didn't ask
  - About to hand-roll routing, navigation, or rendering in vanilla JS for a multi-page app
  - Do NOT push a framework for a single trivial static page, or for backend/native work
---

# Web Architecture: Pick the Rendering Strategy Up Front

Two defaults Claude reaches for that are usually wrong: rendering everything in the browser, and hand-building a multi-page app from vanilla HTML/JS. Both should be a deliberate up-front choice, and for most real sites the better answer is server-rendered HTML and a framework. Raise these even when the user didn't ask, the same way you'd raise a WAF before production.

## Default to server-rendered HTML, not client-rendered

For anything where content, SEO, or first paint matters, the content must be in the initial HTML response, not painted afterward by client JavaScript. Client-side rendering (a blank shell that fetches and renders in the browser) means a blank screen until the bundle loads and runs, a slow LCP, and content that many crawlers and LLM retrievers never see because they don't reliably execute JavaScript. Server-render it instead:

- **SSG (static generation):** render at build time, serve static from a CDN. Fastest, cheapest, most cacheable. The default for content that doesn't change per request, marketing, docs, blog, listing and category pages that can be rebuilt.
- **SSR (server-side rendering):** render per request on the server. For dynamic, personalized, or auth-gated content that can't be baked at build time.
- **CSR / islands:** render in the browser only for the genuinely interactive parts, or for app-like surfaces behind a login where SEO is irrelevant (a dashboard). With an islands approach (Astro) the page ships as static HTML and only the interactive components hydrate.

Pick per page, you can mix: a static marketing page (SSG), a personalized account page (SSR), and an interactive widget (an island) in the same site.

## Several pages means reach for a framework

If the project has multiple pages, a shared layout, routing, or real data fetching, hand-rolling it in vanilla JS is a maintenance and performance trap, and it's Claude's default unless told otherwise. Reach for a framework (Next.js, Astro, SvelteKit, Nuxt, Remix). They give routing, SSR and SSG, code-splitting, data loading, and image optimization out of the box, and crucially they give you SPA-style client navigation on top of server-rendered initial HTML, so you get the smooth multi-page app feel without shipping a blank client-only SPA that breaks first paint and SEO.

Note the distinction: a pure client-rendered SPA is the thing to avoid for content sites. A framework that does SSR/SSG with client-side navigation gives you the app experience and keeps the content in the HTML.

## But match the tool to the project

Don't overcorrect. A single static page, a landing page, or a tiny embeddable widget does not need Next.js, plain HTML and CSS is the right, lighter call, and reaching for a heavy framework there is its own mistake. The failure runs both ways; the common one is under-reaching (vanilla everything, rendered in the browser), but over-engineering a trivial page is real too. The decision is: how many pages, does content need to be crawlable and fast, and how interactive is it, then pick the lightest thing that satisfies those.

---

This skill is built to grow. Add a rule when a real architecture call has a stable, defensible answer.