Skip to content

Add SEO prerender, history-based routing, and sitemap generation - #10

Merged
vinc3m1 merged 3 commits into
mainfrom
claude/site-seo-architecture-fcicsy
Jun 16, 2026
Merged

vinc3m1 merged 3 commits into
mainfrom
claude/site-seo-architecture-fcicsy

Conversation

@vinc3m1

@vinc3m1 vinc3m1 commented Jun 15, 2026

Copy link
Copy Markdown
Owner

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): Dropped svelte-spa-router in favor of a minimal custom router that uses location.pathname instead of hashes. Enables real crawlable URLs like /tides/benoa-indonesia/ instead of /#/tides/benoa-indonesia.

  • Static prerender script (scripts/prerender.ts): Generates dist/tides/<slug>/index.html for every station by:

    • Copying the built SPA shell
    • Swapping station-specific SEO <head> tags into a <!-- seo:start -->…<!-- seo:end --> block
    • Injecting crawlable content (example tide rows, nearby links) into #app
    • The SPA clears #app on boot, so real users get the live app; crawlers see the static content
  • SEO 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): Emits dist/sitemap.xml with ~6k station URLs plus the home page.

  • GitHub Pages 404 fallback (dist/404.html): The prerender step copies the SPA shell to 404.html so deep links work on GitHub Pages — the shell boots and self-routes from location.pathname.

  • URL ↔ selection sync (src/App.svelte, src/stores/selection.ts):

    • Deep links (e.g. /tides/benoa-indonesia/) preselect a station on boot
    • In-app navigation updates the shareable URL
    • Plain / visits keep their URL (no rewrite)
  • Updated routing imports: All route components now use the custom link action from src/lib/router.ts instead of svelte-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 #app on boot, sidestepping hydration-mismatch risk entirely.

  • Safe HTML escaping: Station names are escaped for both HTML (&, <, >, ") and JSON-LD (neutralizing <, >, & as \uXXXX so 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 build now runs `vite build

https://claude.ai/code/session_01T7pqWwrzxmdigJRC5gEf66

claude added 3 commits June 15, 2026 02:52
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
@vinc3m1
vinc3m1 merged commit 71e6b2f into main Jun 16, 2026
2 checks passed
@vinc3m1
vinc3m1 deleted the claude/site-seo-architecture-fcicsy branch June 16, 2026 02:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants