Skip to content

fix(handbook): check for a new build on every navigation - #180

Merged
nerdalytics merged 1 commit into
trunkfrom
fix/handbook-version-check
Oct 19, 2026
Merged

nerdalytics merged 1 commit into
trunkfrom
fix/handbook-version-check

Conversation

@nerdalytics

@nerdalytics nerdalytics commented Oct 19, 2026 •

Copy link
Copy Markdown
Owner

Description

After #179 deployed, an open tab kept showing the previous build with v2001.0.0 in the version selector. The server was already correct. version.json returned the new build id, the new worker precached 417 paths that all return 200, and /v2001.0.1/introduction returned 200. The tab stayed stale because the layout asked for the build version once, on mount. GitHub Pages serves every file with max-age=600, so a check in the ten minutes after a deploy can receive the old version.json from the CDN, and no client-side navigation asked again. This PR moves the check to afterNavigate, so every navigation re-checks in the background while the page still renders from the worker's cache.

Changes Made

  • handbook/src/routes/+layout.svelte calls updated.check() from afterNavigate instead of onMount. afterNavigate runs after the initial load and after every client-side navigation.
  • The service worker is unchanged. It stays cache-first and keeps passing version.json through with cache: 'no-store'.
  • The existing effect is unchanged. When updated.current turns true it calls registration.update(), polls until the new worker's cache is the only one, and reloads.
  • The change adds no timer and no interval. If a check lands on a stale CDN copy, the reader's next navigation retries it.

Performance Impact

Each client-side navigation makes one extra request for _app/version.json, which is 27 bytes on the live site. Nothing changes for the core library.

Test Coverage

  • npm run check in handbook/: svelte-check reported 374 files, 0 errors, 0 warnings.
  • BASE_PATH=/beacon npm run build in handbook/ completed.
  • To verify after this deploys, open the site, wait for the next handbook deploy, then click any sidebar link. The tab should reload on its own within a few seconds of the CDN serving the new version.json, without a manual reload.
  • No automated test covers this. The handbook has no browser test setup.

Related Issues

This follows #179. The maintainer reported the stale tab on 2026-10-19.

Checklist

  • Tests added/updated for changes
  • Documentation updated
  • All tests passing
  • Code formatting checked
  • Performance implications considered
  • Breaking changes documented (if applicable)

The layout asked the server for its build version once, on mount. A
check that ran while the GitHub Pages CDN still served the previous
version.json (max-age=600) found nothing, and no later client-side
navigation asked again, so the tab kept the cached build until its
next full load. afterNavigate runs the same check after the initial
load and after every navigation; the page still renders from the
worker's cache first, and a differing version feeds the existing
update-and-reload effect.
@nerdalytics
nerdalytics marked this pull request as ready for review October 19, 2026 15:39
@nerdalytics
nerdalytics merged commit d8d2dda into trunk Oct 19, 2026
12 checks passed
@nerdalytics
nerdalytics deleted the fix/handbook-version-check branch October 19, 2026 16:41
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.

1 participant