web-architecture

# 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.