system-type-spa

name	system-type-spa
description	Domain patterns for single-page application architecture — client-side routing, state management, rendering strategies, authentication, performance, and offline support. Use when designing or evaluating a browser-based SPA, progressive web app, or rich client-side application.

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. Key decisions. Chunk granularity (per route, per feature, per library), preloading strategy for likely next routes, loading state during chunk fetch, handling chunk load failures (version mismatch after deployment).

State Management

Local Component State

When to use. UI state that belongs to a single component — form inputs, toggles, dropdown open/closed, animation state. The default; reach for shared state only when local state creates prop drilling pain. When to avoid. State that multiple unrelated components need. State that must survive component unmounting. Key decisions. When to lift state vs. when to share it. Keeping state as close to where it's used as possible.

Global State (Redux, Zustand, Jotai, Signals)

When to use. State shared across many components — user session, feature flags, shopping cart, notification queue. State that must be inspectable and debuggable (Redux DevTools). State with complex update logic that benefits from centralization. When to avoid. Simple applications where React context or component state suffices. Using global state as a default rather than an escalation — this is the most common state management mistake. Key decisions. Store shape (normalized vs nested), selector granularity (over-subscribing causes re-renders), middleware for side effects, persistence strategy, hydration from SSR.

Server State (React Query, SWR, Apollo)

When to use. Any data that comes from a server and may be stale. These libraries handle caching, revalidation, deduplication, and background refresh — problems you will solve badly if you solve them manually. When to avoid. Purely local state. Offline-first applications where the server is not the source of truth. Key decisions. Cache invalidation strategy, stale-while-revalidate timing, optimistic updates, error retry policy, query key design (determines cache boundaries), prefetching strategy.

URL State

When to use. Filter selections, search queries, pagination, sort order — anything the user should be able to bookmark or share via URL. Often overlooked as a state management tool. When to avoid. Sensitive data. High-frequency updates (every keystroke). State that doesn't make sense to share or bookmark. Key decisions. Serialization format (query params vs path segments), default value handling, URL length limits, backward compatibility when URL schema changes.

Authentication Patterns

Token-Based (JWT)

When to use. SPAs that call APIs on a different domain. When the backend is stateless. When you need to include claims (roles, permissions) in the token to reduce backend lookups. When to avoid. When you can use HTTP-only cookies instead (same-domain APIs) — cookies are harder to steal via XSS. When token revocation is a hard requirement (JWTs are valid until expiry). Key decisions. Storage location (memory vs localStorage — memory is safer, localStorage survives refresh), refresh token rotation, token expiry duration, silent refresh mechanism, logout propagation across tabs.

HTTP-Only Cookie

When to use. When the API is on the same domain (or a subdomain). The most secure browser storage mechanism — not accessible to JavaScript, eliminating the XSS token theft vector. When to avoid. Cross-origin API calls where cookies can't be sent. Mobile app backends where cookies are awkward. Key decisions. SameSite attribute (Strict vs Lax), CSRF protection (double-submit cookie or synchronizer token), cookie scope (domain, path), secure flag enforcement.

OAuth / OIDC Flows

When to use. Third-party login (Google, GitHub, Microsoft). Enterprise SSO. When you don't want to manage passwords. When to avoid. Simple applications with only email/password auth where the OAuth complexity isn't justified. Key decisions. Authorization Code flow with PKCE (required for SPAs — implicit flow is deprecated), redirect vs popup, state parameter for CSRF, token storage after callback, session management across tabs.

Performance

Bundle Size

What it costs. Every kilobyte of JavaScript must be downloaded, parsed, and executed. On a mid-range mobile device, 1 MB of JavaScript can take 3-4 seconds to parse alone. Bundle size is the single largest performance lever for SPAs. Key strategies. Tree shaking (ensure ESM imports), code splitting by route and feature, dynamic imports for heavy libraries, bundle analysis (webpack-bundle-analyzer, source-map-explorer), size budgets enforced in CI, replacing heavy libraries with lighter alternatives.

Rendering Performance

What it costs. Unnecessary re-renders cause jank, input lag, and battery drain. React's reconciliation is fast but not free — large component trees with frequent updates are the primary source of SPA sluggishness. Key strategies. Memoization (React.memo, useMemo, useCallback — but measure first), virtualized lists for large datasets, debounced inputs, avoiding state updates that trigger full tree re-renders, profiler-guided optimization (React DevTools Profiler, Chrome Performance tab).

Network Performance

What it costs. API waterfalls — sequential requests where one fetch depends on another — are the most common cause of slow SPA page loads. Users perceive network-bound delays as the app being slow. Key strategies. Parallel data fetching, request deduplication, prefetching on hover/focus, cache-first patterns for stable data, skeleton screens that match actual layout, avoiding layout shift during load.

Core Web Vitals

What it costs. LCP (Largest Contentful Paint), INP (Interaction to Next Paint), and CLS (Cumulative Layout Shift) directly affect search ranking and user perception. SPAs historically struggle with all three. Key strategies. Preload critical resources, inline critical CSS, reserve space for dynamic content (prevents CLS), break long tasks to keep main thread responsive (improves INP), use loading="lazy" for below-fold images.

Offline and PWA

Service Workers

When to use. Offline support, background sync, push notifications, asset precaching. Any SPA that should work (even partially) without a network connection. When to avoid. Applications where stale data is dangerous (financial dashboards, real-time monitoring). When the team doesn't understand service worker lifecycle — a broken service worker can cache bad code with no recovery path for users. Key decisions. Caching strategy per resource type (cache-first for assets, network-first for API), cache versioning and cleanup, update notification to users ("new version available"), scope management, handling service worker update when tabs are open.

Offline Data

When to use. Applications used in unreliable network conditions — field work, mobile, transit. Forms that should not lose data on disconnection. When to avoid. When the conflict resolution complexity exceeds the offline benefit. When data freshness is critical and stale data causes harm. Key decisions. Local storage technology (IndexedDB for structured data, localStorage for simple key-value), sync strategy (background sync API, manual queue), conflict resolution on reconnection, storage quota management, user communication about offline state.

Common Failure Modes

• Stale deployment cache. Users load cached JavaScript bundles that reference API contracts or chunk filenames that no longer exist. Mitigation: content-hashed filenames, versioned API endpoints, chunk load error handling that forces a page refresh.
• Memory leaks from event listeners and subscriptions. Components mount listeners or subscriptions and never clean them up. Over time, the tab consumes gigabytes. Mitigation: cleanup in useEffect return / componentWillUnmount, WeakRef where appropriate, monitoring tab memory in production.
• White screen of death. An unhandled JavaScript error crashes the entire component tree. Mitigation: error boundaries at route and feature level, fallback UI, error reporting to monitoring service.
• State desynchronization. Client state diverges from server state — the user sees stale data, makes decisions on wrong information, or submits conflicting updates. Mitigation: server state as source of truth (React Query/SWR), optimistic update rollback on failure, staleness indicators.
• Infinite loading states. A failed network request with no timeout or error handling leaves the user staring at a spinner forever. Mitigation: request timeouts, error states with retry, circuit breaker for known-failing endpoints.
• Route-level code split failures. After a deployment, users on old cached pages try to navigate to a route whose chunk filename has changed. The dynamic import fails silently. Mitigation: chunk error detection, automatic page reload on chunk load failure, service worker precaching of route chunks.
• Authentication token expiry during use. The user is mid-workflow when their token expires. The next API call fails, and unsaved work is lost. Mitigation: silent token refresh before expiry, queuing requests during refresh, saving form state to localStorage as backup.
• Hydration mismatch. SSR HTML doesn't match what the client renders, causing React to discard the server-rendered DOM and re-render from scratch — negating the SSR performance benefit. Mitigation: ensure server and client render identical output, suppress hydration warnings only as last resort, avoid browser-only APIs during SSR (window, localStorage).

Anti-Patterns

• Mega-bundle. Shipping the entire application as a single JavaScript file. Users download megabytes of code they won't use on the current page. Split by route at minimum.
• Global state for everything. Putting form input state, UI toggles, and animation state into Redux/Zustand. Global state is for shared, cross-cutting concerns — not a replacement for component state.
• Prop drilling avoidance via global state. Reaching for a global store because props pass through 3 components. Composition (children, render props, context) solves this without the overhead.
• Direct DOM manipulation. Using querySelector or innerHTML alongside a virtual DOM framework. The framework can't track changes it didn't make, leading to subtle rendering bugs.
• Client-side security. Hiding UI elements instead of enforcing permissions on the API. Every API endpoint must validate authorization independently — the client is untrusted.
• Storing secrets in JavaScript. API keys, service credentials, or admin tokens in client-side code. JavaScript source is fully visible to users. Use a backend proxy for authenticated third-party calls.
• SPA for content sites. Building a blog, documentation site, or marketing page as a CSR SPA. These need SEO, fast first paint, and work without JavaScript. Use SSG or SSR.
• Ignoring accessibility. SPAs break native browser accessibility by default — no page load announcements, focus management on route change, or semantic HTML. Accessibility must be designed in, not retrofitted.
• No loading or error states. Assuming every API call succeeds instantly. Every async operation needs three states: loading, success, error. Skipping any of these guarantees a bad user experience.
• Over-abstracting too early. Creating a generic DataFetcher, FormBuilder, or LayoutEngine before understanding the actual use cases. Premature abstraction in frontend code creates rigid, hard-to-debug component hierarchies.