Skip to content

Commit 0bbaa39

Browse files
t3dotggclaude
andcommitted
fix(web): surface a spent chunk reload instead of a stuck splash
A failed startup chunk fetch after the one guarded reload left the boot splash up forever, and a successful reload after a route chunk failure still cleared the guard, which let a persistent failure loop. Move the guard into a tested helper, skip the paint when a reload is scheduled, only re-arm the guard after a boot that fetched every chunk it asked for, and replace the splash with a short message when the auth shell chunk fails for good. Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent 22ac01a commit 0bbaa39

3 files changed

Lines changed: 132 additions & 47 deletions

File tree

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { describe, expect, it, vi } from "vite-plus/test";
2+
3+
import { clearChunkReloadGuard, reloadOnceForChunkLoadError } from "./chunkReloadGuard";
4+
5+
function createStorageStub(): Storage {
6+
const store = new Map<string, string>();
7+
return {
8+
getItem: (key) => store.get(key) ?? null,
9+
setItem: (key, value) => {
10+
store.set(key, value);
11+
},
12+
removeItem: (key) => {
13+
store.delete(key);
14+
},
15+
clear: () => store.clear(),
16+
key: (index) => [...store.keys()][index] ?? null,
17+
get length() {
18+
return store.size;
19+
},
20+
};
21+
}
22+
23+
describe("reloadOnceForChunkLoadError", () => {
24+
it("reloads on the first failure and lets the second one surface", () => {
25+
const storage = createStorageStub();
26+
const reload = vi.fn();
27+
28+
expect(reloadOnceForChunkLoadError(() => storage, reload)).toBe(true);
29+
expect(reload).toHaveBeenCalledTimes(1);
30+
31+
expect(reloadOnceForChunkLoadError(() => storage, reload)).toBe(false);
32+
expect(reload).toHaveBeenCalledTimes(1);
33+
});
34+
35+
it("reloads again after a successful boot cleared the guard", () => {
36+
const storage = createStorageStub();
37+
const reload = vi.fn();
38+
39+
reloadOnceForChunkLoadError(() => storage, reload);
40+
clearChunkReloadGuard(() => storage);
41+
42+
expect(reloadOnceForChunkLoadError(() => storage, reload)).toBe(true);
43+
expect(reload).toHaveBeenCalledTimes(2);
44+
});
45+
46+
it("never reloads when storage is blocked, so a persistent failure cannot loop", () => {
47+
const reload = vi.fn();
48+
const blocked = () => {
49+
throw new DOMException("blocked", "SecurityError");
50+
};
51+
52+
expect(reloadOnceForChunkLoadError(blocked, reload)).toBe(false);
53+
expect(reload).not.toHaveBeenCalled();
54+
expect(() => clearChunkReloadGuard(blocked)).not.toThrow();
55+
});
56+
});
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Split chunks are fetched lazily, so a deploy (or desktop server swap)
2+
// between page load and a later fetch can 404 the old hashed assets. One
3+
// reload picks up the fresh index.html. A sessionStorage flag keeps a
4+
// persistent failure from becoming a reload loop, and a successful boot clears
5+
// it so the next stale deploy gets its own single reload.
6+
const CHUNK_RELOAD_GUARD_KEY = "t3code:chunk-load-reloaded";
7+
8+
/**
9+
* Called from the `vite:preloadError` listener. Reloads at most once per
10+
* failure streak and returns whether it did, so the caller knows whether to
11+
* swallow the event or let the error surface through the normal paths.
12+
*/
13+
export function reloadOnceForChunkLoadError(
14+
getStorage: () => Storage = () => window.sessionStorage,
15+
reload: () => void = () => window.location.reload(),
16+
): boolean {
17+
let alreadyReloaded: boolean;
18+
try {
19+
const storage = getStorage();
20+
alreadyReloaded = storage.getItem(CHUNK_RELOAD_GUARD_KEY) === "1";
21+
if (!alreadyReloaded) storage.setItem(CHUNK_RELOAD_GUARD_KEY, "1");
22+
} catch {
23+
// Without storage the guard cannot survive a reload, so a persistent
24+
// failure would loop forever. Let the error surface instead.
25+
return false;
26+
}
27+
if (alreadyReloaded) return false;
28+
reload();
29+
return true;
30+
}
31+
32+
/** Clears the guard after a successful boot so a later stale deploy can reload again. */
33+
export function clearChunkReloadGuard(getStorage: () => Storage = () => window.sessionStorage) {
34+
try {
35+
getStorage().removeItem(CHUNK_RELOAD_GUARD_KEY);
36+
} catch {
37+
// Blocked storage never held the flag.
38+
}
39+
}

‎apps/web/src/main.tsx‎

Lines changed: 37 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import {
1212
syncDocumentWindowControlsOverlayClass,
1313
} from "./lib/windowControlsOverlay";
1414
import { AppRoot } from "./AppRoot";
15+
import { clearChunkReloadGuard, reloadOnceForChunkLoadError } from "./lib/chunkReloadGuard";
1516

1617
// Electron loads the app from a file-backed shell, so hash history avoids path resolution issues.
1718
const history = isElectron ? createHashHistory() : createBrowserHistory();
@@ -25,38 +26,16 @@ if (isElectron) {
2526

2627
const clerkPublishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string | undefined;
2728

28-
// With split chunks, a deploy (or desktop server swap) between page load and a
29-
// lazy fetch can 404 the old hashed assets. Reload once to pick up the fresh
30-
// index.html; the guard keeps a persistent failure from becoming a reload loop
31-
// and instead lets the error surface through the normal paths.
32-
const CHUNK_RELOAD_GUARD_KEY = "t3code:chunk-load-reloaded";
33-
const readChunkReloadGuard = () => {
34-
// Blocked storage degrades to reloading on every chunk failure, which is
35-
// still better than stranding the page.
36-
try {
37-
return window.sessionStorage.getItem(CHUNK_RELOAD_GUARD_KEY) === "1";
38-
} catch {
39-
return false;
40-
}
41-
};
42-
const writeChunkReloadGuard = (reloaded: boolean) => {
43-
try {
44-
if (reloaded) {
45-
window.sessionStorage.setItem(CHUNK_RELOAD_GUARD_KEY, "1");
46-
} else {
47-
window.sessionStorage.removeItem(CHUNK_RELOAD_GUARD_KEY);
48-
}
49-
} catch {
50-
// See readChunkReloadGuard.
51-
}
52-
};
29+
// A failed split-chunk fetch usually means the hashed assets went stale under
30+
// a deploy; one guarded reload picks up the fresh index.html.
31+
let chunkLoadFailed = false;
32+
let reloadScheduled = false;
5333
window.addEventListener("vite:preloadError", (event) => {
54-
if (readChunkReloadGuard()) {
55-
return;
34+
chunkLoadFailed = true;
35+
if (reloadOnceForChunkLoadError()) {
36+
reloadScheduled = true;
37+
event.preventDefault();
5638
}
57-
writeChunkReloadGuard(true);
58-
event.preventDefault();
59-
window.location.reload();
6039
});
6140

6241
const app = <AppRoot router={router} />;
@@ -73,22 +52,33 @@ const managedAuthShellModule =
7352
: null;
7453

7554
// The index.html boot splash lives inside #root, and React's first commit
76-
// clears it. Resolve everything that first commit needs — the selected
77-
// managed-auth runtime and the initial route's split chunks — before
55+
// clears it. Resolve everything that first commit needs, the selected
56+
// managed-auth runtime and the initial route's split chunks, before
7857
// rendering, so the splash holds until real UI paints instead of dropping to
7958
// a blank window while chunks download.
80-
void Promise.all([
81-
managedAuthShellModule?.then((module) => module.default) ?? null,
82-
router.load(),
83-
]).then(([ManagedAuthShell]) => {
84-
writeChunkReloadGuard(false);
85-
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
86-
<React.StrictMode>
87-
{ManagedAuthShell && clerkPublishableKey ? (
88-
<ManagedAuthShell publishableKey={clerkPublishableKey}>{app}</ManagedAuthShell>
89-
) : (
90-
app
91-
)}
92-
</React.StrictMode>,
93-
);
94-
});
59+
void Promise.all([managedAuthShellModule?.then((module) => module.default) ?? null, router.load()])
60+
.then(([ManagedAuthShell]) => {
61+
// A route chunk failure still resolves router.load(): the error is parked in
62+
// the lazy component and surfaces through the route error boundary. Skip the
63+
// paint when a reload is on its way, and only re-arm the guard after a boot
64+
// that fetched every chunk it asked for.
65+
if (reloadScheduled) return;
66+
if (!chunkLoadFailed) clearChunkReloadGuard();
67+
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
68+
<React.StrictMode>
69+
{ManagedAuthShell && clerkPublishableKey ? (
70+
<ManagedAuthShell publishableKey={clerkPublishableKey}>{app}</ManagedAuthShell>
71+
) : (
72+
app
73+
)}
74+
</React.StrictMode>,
75+
);
76+
})
77+
.catch((error: unknown) => {
78+
// The auth shell chunk failed and the guarded reload is spent. Say so
79+
// instead of leaving the splash up forever.
80+
if (reloadScheduled) return;
81+
console.error("T3 Code failed to load its startup chunks.", error);
82+
const bootShell = document.getElementById("boot-shell");
83+
if (bootShell) bootShell.textContent = "T3 Code could not load. Reload to try again.";
84+
});

0 commit comments

Comments
 (0)