Reload once when a lazy route chunk 404s after a deploy (GlitchTip #160)
ci / server (sqlite) (pull_request) Successful in 18s
ci / lint (pull_request) Successful in 1m5s
ci / nox (pull_request) Successful in 1m10s
ci / server (mysql) (pull_request) Successful in 1m23s
ci / client (pull_request) Successful in 2m48s
ci / sidecar (pull_request) Successful in 3m6s
ci / image (pull_request) Successful in 9m55s
ci / sourcemaps (pull_request) Skipped
ci / deploy (pull_request) Skipped

A tab opened before a deploy asks for the old hashed Landing CSS or JS
file, gets a 404, and the navigation dies with "Unable to preload CSS".
router.onError now loads the destination again, and vite:preloadError
reloads for imports outside the router. A sessionStorage stamp limits
this to one reload per 60 seconds so a chunk missing for another reason
still surfaces as an error.

https://bugs.extant2000.com/caelum/issues/160

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1
2026-11-17 13:51:38 -05:00
co-authored by Claude Opus 5.5
parent 1d341622e3
commit 73b315f37e
3 changed files with 186 additions and 0 deletions
+3
View File
@@ -5,6 +5,7 @@ import App from './App.vue';
import { initSentry } from './sentry.js';
import { initAppearance } from './services/appearance.js';
import { log } from './utils/log.js';
import { installStaleChunkRecovery } from './utils/stale-chunk.js';
import './assets/style.css';
// Apply the saved theme/density before mount so there's no flash of the wrong one.
@@ -19,4 +20,6 @@ const app = createApp(App);
initSentry(app, router);
app.use(createPinia());
app.use(router);
// A deploy renames the lazy view chunks; load the page again when one 404s.
installStaleChunkRecovery({ win: window, router });
app.mount('#app');
+66
View File
@@ -0,0 +1,66 @@
// Recovers from a route chunk that no longer exists on the server.
//
// Every view is a lazy import (routes.js). A deploy replaces the hashed files
// under /assets, so a tab opened before the deploy asks for Landing-<old>.css
// or Landing-<old>.js, gets a 404, and the navigation dies with "Unable to
// preload CSS" or "Failed to fetch dynamically imported module". Loading the
// page again fetches the new index.html and the new chunk names.
//
// The reload happens at most once per RELOAD_WINDOW_MS, tracked in
// sessionStorage, so a chunk that is missing for another reason surfaces as
// an error instead of reloading forever.
export const RELOAD_KEY = 'caelum:chunk-reload-at';
export const RELOAD_WINDOW_MS = 60_000;
const CHUNK_ERROR_RE = /Unable to preload CSS|Failed to fetch dynamically imported module|error loading dynamically imported module|Importing a module script failed/i;
export function isChunkLoadError(err) {
const msg = typeof err === 'string' ? err : err?.message;
return typeof msg === 'string' && CHUNK_ERROR_RE.test(msg);
}
// Navigates to `target` (or reloads when target is null) unless a recovery
// already ran within the window. Returns true when it navigated.
export function recoverOnce({ storage, now = Date.now(), go, target = null }) {
let last;
try {
last = Number(storage.getItem(RELOAD_KEY));
} catch {
return false;
}
if (Number.isFinite(last) && last > 0 && now - last < RELOAD_WINDOW_MS) return false;
try {
storage.setItem(RELOAD_KEY, String(now));
} catch {
return false;
}
go(target);
return true;
}
// Wires the recovery into the router and Vite's preload event.
//
// router.onError sees route chunk failures with the destination, so it loads
// that URL directly. vite:preloadError also fires for imports outside the
// router; its handler waits one task so the router, whose error path runs in
// microtasks, claims a route failure first and the window keeps a shared
// guard.
export function installStaleChunkRecovery({ win, router }) {
const storage = win.sessionStorage;
const go = (target) => {
if (target) win.location.assign(target);
else win.location.reload();
};
let handled = false;
router.onError((err, to) => {
if (!isChunkLoadError(err)) return;
handled = recoverOnce({ storage, go, target: to?.fullPath ?? null }) || handled;
});
win.addEventListener('vite:preloadError', (event) => {
win.setTimeout(() => {
if (handled) return;
if (isChunkLoadError(event?.payload)) handled = recoverOnce({ storage, go });
}, 0);
});
}
+117
View File
@@ -0,0 +1,117 @@
// Tests for client/src/utils/stale-chunk.js. Run with `node --test`.
//
// GlitchTip Caelum #160: "Unable to preload CSS for /assets/Landing-Bjm0Znvs.css"
// after a deploy renamed the chunk. The router must load the destination
// again once, and must not loop when the chunk is gone for good.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
isChunkLoadError, recoverOnce, installStaleChunkRecovery, RELOAD_KEY, RELOAD_WINDOW_MS,
} from '../src/utils/stale-chunk.js';
function memoryStorage() {
const m = new Map();
return { getItem: (k) => (m.has(k) ? m.get(k) : null), setItem: (k, v) => m.set(k, String(v)) };
}
function fakeWindow() {
const listeners = {};
const timers = [];
const calls = [];
return {
calls,
sessionStorage: memoryStorage(),
location: { assign: (u) => calls.push(['assign', u]), reload: () => calls.push(['reload']) },
addEventListener: (type, fn) => { listeners[type] = fn; },
setTimeout: (fn) => timers.push(fn),
fire: (type, event) => listeners[type](event),
runTimers: () => { while (timers.length) timers.shift()(); },
};
}
function fakeRouter() {
let handler;
return { onError: (fn) => { handler = fn; }, fail: (err, to) => handler(err, to) };
}
test('chunk load messages from Chrome, Firefox and Safari are recognised', () => {
assert.ok(isChunkLoadError(new Error('Unable to preload CSS for /assets/Landing-Bjm0Znvs.css')));
assert.ok(isChunkLoadError(new TypeError('Failed to fetch dynamically imported module: https://x/assets/Landing-a.js')));
assert.ok(isChunkLoadError(new TypeError('error loading dynamically imported module')));
assert.ok(isChunkLoadError(new TypeError('Importing a module script failed.')));
});
test('other errors are left alone', () => {
assert.equal(isChunkLoadError(new Error('Network error talking to /auth/me')), false);
assert.equal(isChunkLoadError(null), false);
assert.equal(isChunkLoadError({}), false);
});
test('a route chunk failure loads the destination once', () => {
const win = fakeWindow();
const router = fakeRouter();
installStaleChunkRecovery({ win, router });
router.fail(new Error('Unable to preload CSS for /assets/Landing-Bjm0Znvs.css'), { fullPath: '/' });
assert.deepEqual(win.calls, [['assign', '/']]);
});
test('the preload event does not reload a second time after the router handled it', () => {
const win = fakeWindow();
const router = fakeRouter();
installStaleChunkRecovery({ win, router });
const err = new Error('Unable to preload CSS for /assets/Landing-Bjm0Znvs.css');
win.fire('vite:preloadError', { payload: err });
router.fail(err, { fullPath: '/nox/docs?x=1' });
win.runTimers();
assert.deepEqual(win.calls, [['assign', '/nox/docs?x=1']]);
});
test('a preload failure outside the router reloads the page', () => {
const win = fakeWindow();
installStaleChunkRecovery({ win, router: fakeRouter() });
win.fire('vite:preloadError', { payload: new Error('Unable to preload CSS for /assets/Chart-1.css') });
win.runTimers();
assert.deepEqual(win.calls, [['reload']]);
});
test('a second failure inside the window does not reload again', () => {
const storage = memoryStorage();
const went = [];
const go = (t) => went.push(t);
assert.equal(recoverOnce({ storage, now: 1_000_000, go, target: '/' }), true);
assert.equal(recoverOnce({ storage, now: 1_000_000 + RELOAD_WINDOW_MS - 1, go, target: '/' }), false);
assert.deepEqual(went, ['/']);
assert.equal(storage.getItem(RELOAD_KEY), '1000000');
});
test('a failure after the window recovers again', () => {
const storage = memoryStorage();
const went = [];
const go = (t) => went.push(t);
recoverOnce({ storage, now: 1_000_000, go, target: '/' });
assert.equal(recoverOnce({ storage, now: 1_000_000 + RELOAD_WINDOW_MS, go, target: '/login' }), true);
assert.deepEqual(went, ['/', '/login']);
});
test('unusable storage means no reload, so no loop', () => {
const storage = { getItem: () => { throw new Error('denied'); }, setItem: () => { throw new Error('denied'); } };
const went = [];
assert.equal(recoverOnce({ storage, go: (t) => went.push(t), target: '/' }), false);
assert.deepEqual(went, []);
});
test('non-chunk router errors do not navigate', () => {
const win = fakeWindow();
const router = fakeRouter();
installStaleChunkRecovery({ win, router });
router.fail(new Error('boom'), { fullPath: '/' });
win.runTimers();
assert.deepEqual(win.calls, []);
});
test('main.js installs the recovery on the router', async () => {
const { readFile } = await import('node:fs/promises');
const src = await readFile(new URL('../src/main.js', import.meta.url), 'utf8');
assert.match(src, /installStaleChunkRecovery\(\{\s*win:\s*window,\s*router\s*\}\)/);
});