ADR-013 — History API routing

Status · Accepted Date · 2026-04-28 Supersedes · ADR-004 (hash routing) TA anchor · §stack · §components/router

Context

ADR-004 chose hash routing because it works with any static file server without configuration. SvelteKit's file-based routing uses the History API by default and produces clean URLs (/explore, /fly, /missions). At production scale, clean URLs matter for sharing, SEO, and basic user trust. The nginx configuration change required is one line.

Decision

History API routing via SvelteKit's built-in router. Routes are /moon, /explore, /plan, /fly, /missions, /earth. Query params use standard URLSearchParams: /fly?mission=curiosity, /missions?dest=MARS.

Rationale

SvelteKit's router is the right tool — it handles code splitting, prefetching, and navigation transitions out of the box. Clean URLs are table stakes for a production application. The nginx catch-all (try_files $uri /index.html) is a one-line addition that was always going to be needed.

Alternatives considered

• Hash routing — see ADR-004; works without server config; aesthetically poor; no SEO benefit; rejected for production.
• Hand-written History API router — RFC-001's proposed approach; superseded by SvelteKit's router which is more capable and battle-tested.

Consequences

Positive: clean URLs; SvelteKit handles code splitting and prefetching automatically; SEO-ready. Negative: requires server-side catch-all redirect (one nginx line); direct URL access requires server config.

Implementation notes

SvelteKit file-based routing: src/routes/explore/+page.svelte, src/routes/fly/+page.svelte, etc. GitHub Pages requires a 404.html redirect workaround for History API — a known pattern, one file.