fix(react-router): stop lazyRouteComponent flashing the error component while reloading #8433
main fromrefs/pull/8433/head·opened Fixes #8377.
🎯 Changes#
lazyRouteComponent already recovers from a stale chunk after a deploy: it sets a sessionStorage guard, calls window.location.reload() and suspends on a never-resolving promise.
But reload() is asynchronous and error is never cleared, so any render between the reload request and the document going away re-enters the if (error) branch, finds the guard key already set, and falls through to throw error. The route's errorComponent renders the import failure for a moment until the reload lands — and, for anyone wiring the router's defaultOnCatch to error tracking, the failure is reported as unhandled even though the user recovers.
This remembers the reload request in the closure and keeps suspending on later renders instead of re-evaluating the guard:
let error: any
+ let reloadRequested = false
const lazyComp = function Lazy(props: any) {
if (error) {
+ if (reloadRequested) {
+ throw new Promise(() => {})
+ }
+
if (isModuleNotFoundError(error) && ...) {
const storageKey = `tanstack_router_reload:${error.message}`
if (!sessionStorage.getItem(storageKey)) {
sessionStorage.setItem(storageKey, '1')
+ reloadRequested = true
window.location.reload()
The sessionStorage guard is deliberately untouched. It exists to stop a reload loop when a chunk is missing for some reason other than a new deployment, and it still does: the closure flag only covers renders within the page that is already reloading, so a fresh page load still surfaces the error.
Why this is worth fixing beyond the visual flash#
Users do recover, so the flash is minor on its own. The problem is that a recovered failure becomes indistinguishable from an unrecovered one in error tracking. On one of our production apps this is the single largest source of client errors — ~400 events across ~93 issue groups (one per dead chunk URL, since the URL is in the message), at a deploy every 5–10 minutes. We spent a while assuming users were stranded on an error screen before the minified culprit frame showed they were being reloaded correctly the whole time. Details and breadcrumbs in #8377.
Tests#
Added packages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsx, following the existing issue-NNNN convention:
- A render after the reload is requested keeps suspending instead of throwing, and does not trigger a second reload. Without the source change this fails with
expected TypeError: Failed to fetch dynamically im… to be an instance of Promise. - A later page load with the guard already set still throws, so the anti-loop behaviour is not weakened. This passes both with and without the fix, on purpose.
Scope#
React only. For reference, I checked the other two frameworks:
- solid-router has the same re-entry: its reload branch
returns{ default: () => null }instead of throwing, but a second render still reachesthrow error. I left it out to keep this reviewable and because I can't exercise it as confidently — happy to add it here or in a follow-up if you'd prefer it in one go. - vue-router already guards this with its
attemptedReloadclosure flag, so it needs no change.
✅ Checklist#
- I have followed the steps in the Contributing guide.
- I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
- I fully understand the code in this pull request, including any code generated with AI assistance.
Full @tanstack/react-router suite: 93 files, 1180 passed, 1 skipped, no type errors.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
Bug Fixes
- Fixed lazy-loaded route failures during stale-chunk recovery so the error screen no longer briefly appears while a page reload is pending.
- Prevented repeated reload requests during the same recovery attempt.
- Preserved error reporting when the reload safeguard is already active.
Tests
- Added regression coverage for reload behavior and subsequent error handling.
- 1
I tested the change proposed here against
@tanstack/react-router@1.170.46, after encountering the error-screen flash in our production app (my report is in #8377).Without the change, a second render after the reload request throws the import error. With it, subsequent renders remain suspended, only one reload is requested, and the existing guard still prevents a reload loop across page loads.
I also applied it temporarily through pnpm in our TanStack Start app. The regression checks passed against both published runtime formats, and the app's production build succeeded with the fix included in the client bundle. I haven't verified the patched behavior across two real deployments, so this is local test and build confirmation rather than a production validation.
@Sheraff @schiller-manuel is there anything blocking this fix, or any additional regression coverage you'd like? I can help with a focused follow-up if needed.
quanglam2807(GitHub profile, opens in a new tab) linked this to fix #8377
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Advanced
Run ID:
4d68b52e-47a8-4dba-83d8-481e89a29d03📥 Commits
Reviewing files that changed from the base of the PR and between 8e164d28f9e9eb1a7301109230d7ece9817492a8 and c6e404b8504d68d6f38a94bbce4a3c26f9dea4ef.
📒 Files selected for processing (3)
.changeset/lazy-route-component-reload-reentry.mdpackages/react-router/src/lazyRouteComponent.tsxpackages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsxIncluded review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.
📝 Walkthrough
Walkthrough#
Changes#
Lazy route reload handling
packages/react-router/src/lazyRouteComponent.tsx,.changeset/lazy-route-component-reload-reentry.mdlazyRouteComponentrecords when it requests a reload and keeps suspending during subsequent renders. The changeset declares a patch release.packages/react-router/tests/issue-8377-lazy-chunk-reload-reentry.test.tsxPriority: ➖ Normal
Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Bug fix · Severity of issue fixed: Medium
Merge Risk: ⚪ Minimal · up to
c6e40The reload re-entry behavior and existing anti-loop guard are covered by the changed regression tests. No merge-blocking risk is identified.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
#8377requireslazyRouteComponentto remain pending after it requests a stale-chunk reload, while preserving thesessionStorageanti-loop guard. The change adds the closure flag `reloadReque…lazyRouteComponentupdate, and the regression tests all support Issue#8377. The changes do not add unrelated product behavior or unrelated files.✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share