Skip to content

Use versioned bundles to prevent stale UI after deploys - #8

Merged
aliorhun merged 2 commits into
mainfrom
fix/versioned-build-assets
Sep 28, 2026
Merged

aliorhun merged 2 commits into
mainfrom
fix/versioned-build-assets

Conversation

@aliorhun

Copy link
Copy Markdown
Contributor

Summary

This fixes the recurring case where MathNote renders but the UI becomes non-interactive after a GitHub Pages/PWA deployment.

Root cause

The application bundle was always published at fixed URLs:

  • ./app.js
  • ./app.css

With a service worker and browser HTTP cache in front of GitHub Pages, an HTML document from one deployment could be paired with JavaScript/CSS from another deployment. A single DOM mismatch can then stop application initialization and make every control appear dead.

Fix

  • emit content-hashed application assets on every build:
    • ./assets/app-<hash>.js
    • ./assets/app-<hash>.css
  • inject the exact generated bundle URLs into dist/index.html
  • precache those exact bundle URLs
  • keep hashed bundle assets cache-first because their URLs are immutable
  • keep navigation and the manifest network-first with offline fallback
  • move service-worker registration into a tiny inline HTML bootstrap
  • register the service worker with updateViaCache: 'none'
  • keep service-worker recovery independent from the main app bundle, so a runtime failure cannot prevent future SW updates
  • extend the verifier to reject fixed-name app bundles and ensure HTML/SW reference the same hashed files

Recovery behavior

Even an older active MathNote service worker does not have a cached entry for a newly hashed bundle URL, so once it receives the new HTML it must fetch the matching new bundle from the network. Old HTML continues to reference its matching old bundle. This removes cross-deployment HTML/JS mixing by construction.

@aliorhun
aliorhun merged commit de1e8bd into main Sep 28, 2026
2 checks passed
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