Single-page application

What it is

A single-page application, also written single-page app and usually shortened to SPA, is a web application that loads one HTML document and then changes that document with JavaScript instead of asking the server for a new page. Clicking a link inside it does not unload the page. A script catches the click, fetches whatever data the next view needs, rewrites part of the DOM and updates the address bar, so the URL still says where the reader is.

No standard owns the term, and the people who build the tools admit as much. Next.js opens its guide to the subject with “The definition of a SPA varies.” and then fixes one for its own use, which it calls a strict SPA. It has two traits. A single HTML file serves the whole app, and JavaScript in the browser takes care of every route, every page transition and every request for data. And the page never reloads in full: when the route changes, scripts on the client rewrite the DOM of the page that is already open and load data when it is wanted, instead of asking the server for a fresh document. This article uses that definition because it is the most direct one on offer and names the property everything else depends on, a document that is never replaced.

The browser parts are standard. The HTML Standard’s History interface gives a page history.pushState(), which adds a new entry to the session history and sets the URL without loading anything, and history.replaceState(), which rewrites the current entry instead. When the reader goes Back or Forward between those entries, the browser fires a popstate event at the window and leaves the redrawing to the page. The newer Navigation API, which the standard presents as the successor to the classic location and history APIs, works from the other end: a navigate event fires when a navigation begins, and its intercept() method turns that navigation into a same-document one that the page handles itself.

The opposite is the ordinary multi-page website, where every link asks the server for a fresh document and the browser throws the old one away. Whether a page’s HTML is made once by a static site generator or on each request by server-side rendering is a separate question, about how the HTML is produced rather than what happens after it arrives. Next.js blurs the line on purpose: its static export writes an HTML file for every route, and moving between them still happens on the client.

Why it matters

Because the document is never replaced, whatever lives in it survives a click: a half-filled form, a playing video, the scroll position of a side panel, data already fetched. Only the data the next view needs has to cross the network, not a whole new page with its header, styles and scripts. A change of view can be as small as rewriting one region of the page.

Next.js names the costs in the same breath as the definition. A strict SPA often has to load a large amount of JavaScript before the page can be interactive, and client data waterfalls, where one request can start only after another has come back, are hard to manage. Anything that reads the page without running scripts pays as well. With one HTML file behind every route, a crawler that does not run JavaScript gets the same nearly empty document whatever URL it asks for. Next.js makes the same point about its own browser-only components: anything that indexes the page without running scripts gets the fallback, not the component.

Its answer is to keep the client-side navigation and move the rest. Next.js splits JavaScript bundles automatically and generates multiple HTML entry points into different routes, so a visitor does not load code a route does not need. Its next/link component prefetches routes, which makes route changes feel as immediate as those in a fully client-rendered SPA while keeping the application’s routing state in the URL, where it can be linked to and shared. A static export goes further and writes a fully rendered page for each route, so visitors get content without waiting for the client bundle, while client-side transitions between pages stay as quick as in a strict SPA.

Nor is the choice made once and for all. Next.js describes a project that starts as a static site, or even as a strict SPA rendered entirely on the client, and adds server features as it grows, and it says an existing SPA can move across without being rewritten from scratch.

What it looks like in practice

The router below, written for this article, is the smallest working version of the idea. It assumes the page has a <main> element and that the server answers every app path with the same HTML document. The two views stand in for whatever the app really shows.

// router.js
const views = {
  "/": { title: "Orders", text: "Your recent orders." },
  "/settings": { title: "Settings", text: "Delivery preferences." },
};
const main = document.querySelector("main");

function show(path, moveFocus) {
  const view = views[path] ?? views["/"];
  const heading = document.createElement("h1");
  const body = document.createElement("p");
  heading.textContent = view.title;
  heading.tabIndex = -1;
  body.textContent = view.text;
  main.replaceChildren(heading, body);
  document.title = view.title;
  if (moveFocus) heading.focus();
}

document.addEventListener("click", (event) => {
  const link = event.target.closest("a[href]");
  const modified = event.metaKey || event.ctrlKey || event.shiftKey;
  if (!link || link.origin !== location.origin) return;
  if (modified || event.button !== 0) return;
  event.preventDefault();
  history.pushState(null, "", link.href);
  show(location.pathname, true);
});

window.addEventListener("popstate", () => show(location.pathname, true));
show(location.pathname, false);

The click handler takes over plain left clicks on links to the same origin and lets modified clicks through, so opening a link in a new tab still works. preventDefault() stops the browser’s own navigation, and pushState() records a new session history entry with the link’s URL; its middle argument is there only for historical reasons, which is why it is an empty string. show() replaces the view, sets the document title and moves focus to the new heading, which a tabIndex of -1 makes focusable from script while keeping it out of the Tab order. The popstate listener redraws the matching view when the reader goes Back or Forward, and the last line draws whichever URL the page was opened at, which only works if the server sends the same document for /settings as for /. A real app would also show its own not-found view instead of quietly falling back to the start page, and would leave links to files and to other parts of the site alone.

The company’s Next.js 16 frontend shows the cost side of this on a real product. Its portfolio entry describes an authenticated dashboard that had to feel quick and stay genuinely interactive, and names what happens when everything is fetched on the client: the first load drags, and the N+1 pattern appears, with every component waking up and sending its own request until a single page becomes a cascade of round trips. That is the client data waterfall the Next.js guide warns about, met in practice. The fix kept client-side interactivity where it mattered and moved the first fetch to the server. On the dashboard and the big directory listings, a factory called createPrefetchedServerPage hands each page to the client with its data already in place. The entry is candid about the rest: the other authenticated pages are still rendered on the client and wait their turn, so it describes a migration that works and has an obvious next page, not one that is complete.

Where it goes wrong

The Back button leaves the app. If a script swaps views without calling pushState(), the session history has no entry for them. Back skips every view the reader saw and leaves the app altogether, and a reload lands on whatever URL the app was first opened at. Push an entry for each view a reader would call a page, use replaceState() for changes that should not become steps of their own, such as a filter being typed, and handle popstate. Next.js argues for keeping routing state in the URL for the same reason: it is what lets a view be linked to and shared.

A deep link meets a server that knows one file. In a strict SPA one HTML file serves every route, but the address bar shows /settings, and that is what the browser asks for on a reload or when someone opens a shared link. A server that only has index.html answers with a 404. Either configure the server to answer every app path with the document, or generate a file per route. Next.js’s static export does the second: its out folder holds files such as index.html, 404.html and blog/post-1.html, and its guide shows an nginx rule, try_files $uri $uri.html $uri/ =404;, that maps a clean URL onto the matching file.

Focus stays where the old view was. pushState() changes the session history and the URL and nothing else. After a script swaps the view, keyboard focus stays on the link that was clicked, or is lost if the element holding it was removed, and nothing tells assistive technology that a new view has arrived unless the page does. Set the title and move focus to the new view’s heading, as the example does. The Navigation API takes on more of this itself. A navigation handled with intercept() resets focus by default, to the first element with autofocus or else to the body, and once the handler finishes, the browser signals completion to the user, which the standard says includes assistive technology. An app that places focus itself opts out with focusReset: "manual".

Everything is paid for up front. A strict SPA often has to load a large amount of JavaScript before anything is interactive, and its first data requests start only once that code runs. Split the bundle by route, so that a visitor downloads only what the current view needs, and start the first requests on the server. The Next.js pattern for this fetches data in a Server Component without awaiting it and passes the promise to a Client Component, which unwraps it with use(). Because the request begins before the rest of the app renders, the guide says, the response can start streaming at once, and the client is spared a waterfall of requests, each waiting for the one before it.

Further reading

• How to build single-page applications with Next.js — the strict SPA definition, what it costs, and the patterns Next.js uses to keep client-side navigation while moving work to the server.
• HTML Standard: The History interface — pushState(), replaceState() and how session history entries are added and replaced.
• HTML Standard: Navigation API — the navigate event, intercept(), and the focus and scroll handling that comes with it.
• How to create a static export of your Next.js application — one HTML file per route, what a static export cannot do, and serving clean URLs with nginx.