SPA Fallback
Definition
An SPA fallback is a piece of host configuration, not code in your site. It says: if a request matches no file on disk, do not answer with 404 — serve the site's single HTML document with a 200 status and let the browser work out the rest. The rule exists because a single-page application invents its own addresses. Its router knows about '/about', '/reports/2024' and '/settings/profile', but the host only ever received one HTML file, so from its point of view none of those paths exist. Hosts name the same idea differently: a rewrite to index.html, a try_files directive in nginx, a catch-all route, or simply a checkbox labelled single-page app. The detail that matters is that it must be a rewrite rather than a redirect, because the address in the bar has to stay exactly as the visitor typed it or the router will never see the path it needs.
Why It Matters
Without the fallback an SPA is broken in precisely the ways people notice. Deep links shared in chat return a 404 page. Refreshing on any screen other than the home page throws the visitor out. Search engines crawling an internal link find nothing at the other end. Worst of all, the bug is invisible while you build, because local development servers switch the fallback on by default — so it appears for the first time on the live site, usually reported by whoever bookmarked a page. It is a one-line fix that costs a launch day when nobody involved knows the term.
How It Works
A request arrives for '/reports/2024'. The host looks for a matching file, then for an index document inside a directory of that name, and finds neither. With a fallback configured it reads the site's root HTML file instead and returns it with status 200 and a Content-Type of text/html. The browser parses that document, loads the JavaScript bundle, and the application's router reads window.location.pathname — still '/reports/2024', because nothing redirected — and renders the reports view. Real files are untouched by the rule: a request for '/assets/main.css' matches a file, so the fallback never fires for it. That is why the fallback belongs at the end of the matching order rather than in front of it.
Real-World Example
A developer publishes a Vue admin demo to 99helpers and sends the client a link straight to the pricing screen. The client replies that the link is dead, though the site works if you start at the home page and click through. Switching on the single-page app setting fixes both symptoms at once: the deep link loads, and so does a refresh from any screen. Nothing in the 218 KB bundle changed. The host simply stopped saying no to addresses it did not recognise.
Common Mistakes
- ✕Using a 301 or 302 redirect to the home page instead of a rewrite — the address changes before the router sees it, so every deep link lands on the wrong screen
- ✕Applying the fallback to every request including assets — a mistyped stylesheet path then returns HTML with a 200, and the browser reports a baffling parse error rather than a missing file
- ✕Serving the fallback document with a 404 status to keep search engines happy — some crawlers and monitors then treat working screens as broken pages
Related Terms
Single-Page Application
A single-page application loads one HTML file and then rewrites the page in the browser as you navigate, instead of fetching a new document for every link. The address bar still changes; the page never fully reloads.
Client-Side Routing
Client-side routing is when JavaScript in the browser decides which view to show for a given address, instead of the host returning a different document for each one. Links change the screen without a page load.
index.html
index.html is the file a web server returns when a visitor asks for a folder rather than a named file. It is the default document for the site root and for every directory inside it.
Custom 404 Page
A custom 404 page is the page a site shows when someone asks for an address that does not exist, written by you rather than left to the host's default. It is returned with a 404 status code.
HTTP Status Code
An HTTP status code is the three-digit number a server returns at the head of every response, saying what happened to the request. It is the first thing on the first line — a 200 means here is the file, a 404 means there is nothing at that address.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →