Single-Page Application (SPA)
A single-page application loads a document shell and handles later views and navigation mainly through client-side JavaScript.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/single-page-application/
01What it means
A single-page application (SPA) is a web delivery architecture in which the browser usually keeps one document loaded while JavaScript changes views, fetches data, and updates the URL and history. It describes navigation and rendering responsibility, not whether the product literally has one screen or whether its first response contains useful HTML.[1][2]
- 01Load application documentMarkup, styles, scripts
- 02Initialize routeState and current view
- 03Navigate internallyURL + history update
- 04Fetch + renderIncremental DOM change
- 05Restore page behaviorFocus, scroll, announcements
Each transition must deliberately restore URL, history, focus, announcements, scroll, and error behavior.
02Why it matters
SPAs can support fluid, stateful interactions, but they move routing, rendering, error handling, accessibility, and more recovery work into the browser. The choice affects startup cost, resilience, caching, analytics, and search discovery.
03When to use it
Consider an SPA for highly interactive products where state persists across many in-product transitions and the team can own client performance and accessibility. Prefer conventional document navigation or a hybrid when pages are mostly content, work with little JavaScript, or need simple operational behavior.
04How it works
- A server returns an application document with markup, styles, and script references.
- Client code initializes state and renders or activates the current view.
- A router maps URLs to views and updates browser history without full document loads.
- The application fetches data and incrementally updates the DOM as users act.
- The team restores focus, announcements, scroll, errors, and deep-link behavior for each transition.
05A practical example
A collaborative planning tool keeps filters, draft edits, and live presence active while users move among boards. The team chooses an SPA but code-splits routes and explicitly manages page titles, focus, history, and failed data requests.
06Where it breaks
An SPA can ship substantial JavaScript, delay interactivity, fail poorly on weak devices, and recreate browser navigation behavior. It is not inherently faster than a multi-page application, and server rendering does not remove its client runtime costs.
Common mistakes
- Choosing an SPA because it is fashionable rather than because interactions require persistent client state.
- Breaking deep links, back and forward navigation, or scroll restoration.
- Changing views without updating titles, focus, and assistive-technology announcements.
- Treating a quick development server as evidence of production performance.
07Sources
- Rendering on the Webweb.dev · Official technical guidanceRendering on the Web
- History APIMDN Web Docs · Official technical documentationHistory API