Repository navigation
Add SEO prerender, history-based routing, and sitemap generation - #10
Merged
Merged
Conversation
Hash routing made every route invisible to search engines, and the app exposed zero indexable per-location content despite having 6k+ stations. - Replace svelte-spa-router (hash) with a tiny history router (src/lib/router.ts); each station now has a real URL /tides/<slug>/. - Prerender a static, crawlable HTML page per station at build time (scripts/prerender.ts): station-specific <head> (title, description, canonical, OG/Twitter, Place + BreadcrumbList JSON-LD) plus crawlable content injected into #app. mount() clears #app on boot, so the static block is throwaway (no SSR/hydration) — users get the live SPA, crawlers and no-JS visitors get the content. - Generate sitemap.xml (scripts/build-sitemap.ts) + add robots.txt; flesh out the shell <head> with WebApplication JSON-LD and social tags. - Pretty, human-readable slugs (src/seo/slug.ts) derived from the station index at both build and runtime via one shared buildSlugMap, so URLs always agree. Shared pure meta/content builders in src/seo/. - Deep links boot the right station and update the shareable URL on in-app location changes; GitHub Pages 404.html = SPA shell fallback. - Keep the PWA lean: prerendered pages + sitemap excluded from precache; offline navigations fall back to the shell via navigateFallback. https://claude.ai/code/session_01T7pqWwrzxmdigJRC5gEf66
The new offline deep-link test failed in CI: going offline made MapLibre's openfreemap basemap fetch fail with an AJAXError, which CI serialises as the bare minified class name "Me" — not matching the fixture's `openfreemap` ignore pattern (locally the full text includes the URL, so it passed). The existing offline test dodges this because its basemap caches before offline. Stub the basemap with a valid empty style in this test so it doesn't depend on a flaky external resource (route handlers still intercept while offline), isolating what the test actually verifies: a /tides/<slug>/ deep link still routes and renders after going offline. https://claude.ai/code/session_01T7pqWwrzxmdigJRC5gEf66
From a code review of the SEO branch: - Fix a JSON-LD break-out (XSS): buildHeadTags embedded JSON.stringify output directly inside <script type="application/ld+json">. HTML does not decode entities inside a script element and JSON.stringify doesn't escape </script>, so a station name/region/country containing </script> (station data is third-party) could close the tag and inject markup. Escape <, >, & as \uXXXX — still valid JSON. Adds a regression test. - Prerender robustness: use String.replace replacer functions (not strings) so a literal $ in station-derived markup can't be treated as a $&/$1 special pattern and corrupt output; wrap each station in its own try/catch so one bad station logs-and-skips instead of aborting the ~6k build. https://claude.ai/code/session_01T7pqWwrzxmdigJRC5gEf66
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces hash-based routing with history-based URLs and adds static prerendering to make the app crawlable by search engines. Each station now has a real, shareable URL (
/tides/<slug>/) with SEO metadata and example tide data baked in at build time.Key Changes
Custom history-based router (
src/lib/router.ts): Droppedsvelte-spa-routerin favor of a minimal custom router that useslocation.pathnameinstead of hashes. Enables real crawlable URLs like/tides/benoa-indonesia/instead of/#/tides/benoa-indonesia.Static prerender script (
scripts/prerender.ts): Generatesdist/tides/<slug>/index.htmlfor every station by:<head>tags into a<!-- seo:start -->…<!-- seo:end -->block#app#appon boot, so real users get the live app; crawlers see the static contentSEO metadata builders (
src/seo/meta.ts,src/seo/content.ts): Pure, DOM-free functions for building titles, descriptions, Open Graph tags, and JSON-LD structured data. Used by both the prerender script (Bun) and client-side<svelte:head>so static and dynamic metadata always agree.Station slug system (
src/seo/slug.ts): Deterministic, collision-free bijection between station IDs and human-readable slugs (e.g.benoa-indonesia). Built from the same station index at both build time and runtime, ensuring the prerender, sitemap, and router always agree on URLs.Sitemap generation (
scripts/build-sitemap.ts): Emitsdist/sitemap.xmlwith ~6k station URLs plus the home page.GitHub Pages 404 fallback (
dist/404.html): The prerender step copies the SPA shell to404.htmlso deep links work on GitHub Pages — the shell boots and self-routes fromlocation.pathname.URL ↔ selection sync (
src/App.svelte,src/stores/selection.ts):/tides/benoa-indonesia/) preselect a station on boot/visits keep their URL (no rewrite)Updated routing imports: All route components now use the custom
linkaction fromsrc/lib/router.tsinstead ofsvelte-spa-router.Tests: Added unit tests for slug generation, SEO content builders, and metadata; added E2E tests for deep links, prerendered content, and offline station navigation.
Notable Implementation Details
No Svelte SSR/hydration: The prerendered content is throwaway — the SPA clears
#appon boot, sidestepping hydration-mismatch risk entirely.Safe HTML escaping: Station names are escaped for both HTML (
&,<,>,") and JSON-LD (neutralizing<,>,&as\uXXXXso a name like</script>can't break out of the script tag).Replacer functions, not strings: The prerender uses function replacers in
.replace()calls to avoid corruption if a station name contains regex special patterns like$&or$1.Deterministic slug collisions: When multiple stations have the same name+country, the algorithm tries region qualification first, then numeric suffixes — all resolved in a stable sorted order so the map is identical at build time and runtime.
Graceful degradation: If a station file is unreadable or the predictor fails, the prerender still emits the page with metadata and nearby links (no tide rows).
Build pipeline:
bun run buildnow runs `vite buildhttps://claude.ai/code/session_01T7pqWwrzxmdigJRC5gEf66