Give your single page app real 404s and test the route list

  • web
  • testing
  • deployment

Most single page apps I have shipped have the same quiet bug. Ask the server for any path at all, /pricing, /people/42/edit, /wp-login.php, /this-does-not-exist, and it answers 200 OK with the same index.html. The client router boots, decides the path is unknown, and renders a friendly “page not found” screen. A person sees the right thing. Everything that reads status codes sees a working page.

I fixed this recently on one of my projects, and the fix turned out to be two small pieces: a server rule that knows which paths are real, and a test that keeps that rule from drifting away from the app. Here is the approach and the tradeoffs.

Why a soft 404 is worth fixing

The catch-all fallback exists for a good reason. Deep links like /settings?tab=users have no file on disk, so the server has to hand back index.html and let the router take over. The easy way to do that is “if no file matches, serve index.html.” That rule cannot tell a real route from garbage, so garbage gets a 200.

That causes a few real problems:

  • Search engines see infinite pages. Every typo, old link, and bot probe is a page with your title on it. Search tools call these soft 404s and flag them, and they can waste crawl time that should go to your real content.
  • Monitoring lies. An uptime check or a smoke test against a mistyped URL passes. A broken link in your own email campaign looks healthy in logs.
  • Missing assets look fine. If /static/js/old-chunk.js is gone after a deploy, the browser gets HTML with a 200 instead of a 404, and you get a confusing script parse error instead of an obvious missing file.

Adding a noindex meta tag on the client side “not found” screen helps a little, but crawlers have to render the page to see it, and nothing else that reads status codes ever will.

The approach: an explicit list of real routes

The server cannot ask the client router what is valid, so it needs its own list. My rule became:

  1. If the path is a real file (an asset, robots.txt, the sitemap), serve it.
  2. If the path matches a known app route, serve index.html with a 200.
  3. Otherwise, still serve index.html, but with status 404.

Step 3 is the important design choice. I do not want a bare server error page for unknown paths. Serving the app shell with a 404 means the visitor still gets the nice, branded “not found” screen from the router, with navigation back to the home page. Only the status changes.

Here is roughly what that looks like in Caddy, with a shortened route list:

@unknown {
	not file {
		root /srv
	}
	not path_regexp spa "^/(?i)(|login|signup|dashboard|settings|people|people/new|people/[^/]+(/edit)?|help/[^/]+)/?$"
}
handle @unknown {
	root * /srv
	header Cache-Control "no-cache"
	rewrite * /index.html
	file_server {
		status 404
	}
}

A few details in there earned their place:

  • Case insensitive, optional trailing slash. People type /Login and /login/. If the client router accepts those, the server should too, or you return a 404 for a page that renders fine.
  • Dynamic segments become [^/]+. /people/:id/edit matches /people/abc/edit but not /people/a/b/c. Be as strict as the router is, no stricter.
  • no-cache on the 404 response. If a path is unknown today and becomes a real route next week, I do not want a CDN or browser holding on to the old 404.
  • API and asset routes are untouched. The rule only applies after real files and backend routes have had their chance, so it cannot break /api/* or the build output.

The same idea works in nginx, in a serverless rewrite config, or in a small Node server. The shape is always “known routes get the shell with 200, unknown paths get the shell with 404.”

The tradeoff: now you have two route lists

This is the part that made me hesitate. The router in the app already knows every route. Now the server config has a copy. Copies drift. Someone adds a /reports page in the app, forgets the server, and the new page ships with a 404 status. Visitors see it fine, so nobody notices until search traffic to that page never shows up.

Notice that the failure is soft in a good way: because step 3 still serves the app shell, a missed route still renders. Only the status is wrong. That makes the drift cheap to recover from, but also easy to miss, so I wanted a test to catch it before deploy.

A test that reads both lists

The test does not need a running server. It reads the server config as text, pulls out the route pattern, reads the router file, pulls out every declared path, and checks that each one matches:

const fs = require('fs');

const config = fs.readFileSync('deploy/Caddyfile', 'utf8');
const app = fs.readFileSync('src/App.js', 'utf8');

const source = config.match(/not path_regexp spa "([^"]+)"/)[1];
const known = new RegExp(source.replace('(?i)', ''), 'i');

// Turn "/people/:id/edit" into a concrete path we can test.
const concrete = (p) => p.replace(/:[a-z]+/gi, 'abc123');

test('every app route is served with a 200', () => {
	const routes = [...app.matchAll(/path="([^"]+)"/g)].map((m) => m[1]).filter((p) => p !== '*');
	expect(routes.length).toBeGreaterThan(20);
	expect(routes.filter((p) => !known.test(concrete(p)))).toEqual([]);
});

test('junk paths are not on the list', () => {
	for (const p of ['/nope', '/people/a/b/c', '/wp-login.php']) {
		expect(known.test(p)).toBe(false);
	}
});

Two small guards make this trustworthy. The toBeGreaterThan check fails if the regex that finds routes silently stops matching, for example after someone changes how routes are declared. Without it, zero routes found means zero routes missing, and the test passes while checking nothing. The second test proves the pattern is not so loose that it accepts everything, which would quietly bring back the original bug.

Parsing source files with regular expressions is crude, and I am fine with that here. The goal is a cheap tripwire that runs in CI, not a perfect parser. If the routes ever move to a generated manifest, the test can read that instead.

Check the real thing after deploy

Unit tests prove the lists agree. They do not prove the server actually returns the status you expect. So the deploy smoke test now asks for a handful of URLs and checks the codes:

code() { curl -s -o /dev/null -w '%{http_code}' "$BASE$1"; }
check "deep link" 200 "$(code /settings?tab=users)"
check "unknown path" 404 "$(code /nope-xyz)"
check "missing asset" 404 "$(code /static/js/nope.js)"

That last line is my favorite. A missing script returning 404 instead of HTML is the kind of thing you only appreciate the first time a stale tab tries to load an old chunk.

What I would do again

If you have a single page app behind a catch-all fallback, try curl -I against a made-up path on your production site. If it says 200, you have a soft 404. The fix is small: list your real routes on the server, serve the same shell with a 404 for everything else, and add one test so the list keeps up with the app. Visitors will not notice anything changed, and that is the point. The only difference is that your status codes finally tell the truth.