Stale-chunk alert noise + blocking reload prompt¶
1. Problem¶
After each deploy, browser tabs left open from before the release hold stale
chunk hashes — dist/spa is replaced wholesale on every deploy, so a lazy
import() for a route or async component 404s. frontend/src/boot/sentry.ts
already detected this (isChunkLoadError) and showed a "new version
available, reload" toast, but only from the router.onError capture site.
Two gaps:
router.onErrorreported the event to GlitchTip before checkingisChunkLoadError— the one path that detects this condition still alerted on it every time, on every release.- The other three capture sites (
app.config.errorHandler,window.onerror,window.onunhandledrejection) never checkedisChunkLoadErrorat all. A chunk failure from a non-route dynamic import (an async component, not a route) only ever reachesunhandledrejection, which reported it and showed the generic red error toast instead of the reload prompt.
Net effect: every release generated a burst of GlitchTip email/Teams alerts for a condition that already has a working, one-click user-facing recovery — and part of the time the recovery UI didn't even show.
2. Solution¶
Two mechanisms, one job each, in frontend/src/boot/sentry.ts:
- Reporting — extracted the chunk-match regexes (
chunkLoadPatterns) shared byisChunkLoadError()and appended into the existingignoreErrorslist (the same "known, not-actionable" bucketResizeObserver loop/NetworkError/AbortErroralready live in).matchesAny()inglitchtip.tsis the single chokepoint everycaptureError()caller funnels through (includingapi/http.ts), so this covers all four sites — and any future one — without per-caller guessing. - Toast routing — a
toastFor(err, message, caption?)helper wrapsnotifyError: ifisChunkLoadError(err), show the reload prompt instead. Replaces the 3notifyError(...)calls that didn't already special-case chunk errors.router.onErroralready gated correctly and needed no change. - Reload prompt UX —
notifyReloadOnce()moved from a dismissible stickyNotifytoast to aDialog.createwithpersistent: true(blocks Escape/backdrop-click dismiss) and two actions: Reload and Later. A blurred backdrop (.reload-prompt-dialog .q-dialog__backdrop,frontend/src/css/05-quasar-overrides/_q-dialog.scss) makes it visually distinct from a passive toast. Reload-only (no escape hatch) was considered and rejected: the dialog is reachable from every capture site, not just post-deploy chunk failures, andignoreErrorsalready treatsNetworkError/Failed to fetchas expected transient blips — a Reload-only trap would force a mid-form user to lose unsaved work on an ordinary network glitch. "Later" resets the single-shot guard so the prompt can reappear on a later failure in the same session.
New i18n key: later (frontend/src/i18n/common.ts, en + fr). Reuses the
existing new_version_available/reload keys.
3. Explicitly skipped¶
#2194's own decision text floated a proactive version-poll (periodic
index.html fetch, compare entry-chunk hash) if the occurrence threshold was
hit. Skipped here: it solves neither the alert-noise nor the toast-severity
problem, and adds a polling loop with its own staleness edge cases. Revisit
if users start hitting broken routes/blank screens before the reactive
prompt fires — this change doesn't touch that failure mode.
4. Test¶
frontend/tests/integration/chunk-load-reload.spec.ts — dispatches a real
unhandled rejection with a stale-chunk message (the Playwright webServer
runs npm run preview against the production build, so the
import.meta.env.DEV-gated window.__gtTest trigger isn't available) and
asserts: the persistent dialog appears with Reload/Later actions, Escape and
a backdrop click do not dismiss it, and no generic error toast
(.q-notification) appears.
The "no GlitchTip event sent" half isn't independently assertable in that
spec — initGlitchTip is a no-op with no DSN configured in the test env, so
a network-call counter would pass vacuously either way. That guarantee rests
on matchesAny() matching the extended ignoreErrors list.
5. Follow-up (not code)¶
The already-open GlitchTip issues from past stale-chunk noise won't auto-resolve — new occurrences stop, but historical ones stay open until manually resolved/ignored in the GlitchTip UI.