System Type: Single-Page Application (SPA)

Patterns, failure modes, and anti-patterns for browser-based single-page applications.

Rendering Strategies

Client-Side Rendering (CSR)

When to use. Interactive applications where SEO is not critical — dashboards, admin panels, internal tools, authenticated experiences. When the team already has frontend expertise and the app's value is in interactivity, not content discovery. When to avoid. Content-heavy marketing sites, blogs, e-commerce product pages — anything where first meaningful paint and SEO matter. When users are on slow devices or unreliable networks. Key decisions. Shell loading strategy (skeleton screens vs spinners), code splitting granularity, initial bundle size budget, CDN caching for static assets.

Server-Side Rendering (SSR)

When to use. When first contentful paint matters for conversion. Public-facing pages that need SEO. When you need the interactivity of a SPA but can't sacrifice initial load performance. When to avoid. Purely authenticated apps where crawlers never see content. When the backend team can't support a Node.js rendering tier. When the added infrastructure complexity isn't justified by the SEO/performance benefit. Key decisions. Hydration strategy (full hydration, partial, progressive, islands), streaming vs buffered SSR, caching rendered HTML, handling authentication during SSR, server cost for rendering.

Static Site Generation (SSG)

When to use. Content that changes infrequently — documentation, marketing pages, blogs. When you want SPA-like navigation but with pre-built HTML for instant loads. When to avoid. Highly dynamic, personalized content. Pages that change per-user or per-request. Large sites with millions of pages where build times become prohibitive. Key decisions. Build frequency, incremental regeneration strategy, preview/draft workflow, handling dynamic sections within static pages.

Islands Architecture

When to use. Mostly-static pages with isolated interactive widgets. When you want to ship minimal JavaScript and hydrate only the components that need interactivity. When to avoid. Heavily interactive applications where most of the page is dynamic. When shared state between islands creates coupling that negates the isolation benefit. Key decisions. Island boundary identification, shared state between islands, framework choice (Astro, Fresh, 11ty), progressive enhancement baseline.

Client-Side Routing

Hash-Based Routing

When to use. Legacy browser support. Deployments where you can't configure server-side fallback routes (e.g., static file hosting without URL rewriting). Simple applications that don't need clean URLs. When to avoid. Any modern application where clean URLs matter. When anchor links are needed for in-page navigation. Key decisions. None significant — this is a fallback strategy, not a primary choice.

History API Routing

When to use. The default for modern SPAs. Clean URLs, proper browser back/forward behavior, shareable deep links. When to avoid. Environments where the server can't be configured to serve the SPA shell for all routes (static hosting without rewrite rules). In those cases, hash routing or SSG is better. Key decisions. Server fallback configuration (all unmatched routes serve index.html), route-based code splitting, scroll restoration, route transition animations, route guards for authentication.

Route-Based Code Splitting

When to use. Any SPA beyond trivial size. Load code for a route only when the user navigates to it. Essential for keeping initial bundle size manageable. When to avoid. Extremely small applications where the overhead of chunking exceeds the benefit.

…