fix: reload page once if hydration fails to fetch static assets

[brillout-agent]

Closes #3596

With Client Routing, when fetching the page's static assets fails during hydration (flaky connection, or a new frontend deployed while the page was loading), the server-rendered page stays non-interactive and the error surfaces as an unhandled rejection.

Vike now reloads the page in that case, but only once: a page that was itself loaded by a reload isn't reloaded again, so persistent failures can't cause a reload loop.

• The "already reloaded" check uses the Navigation Timing API (performance.getEntriesByType('navigation')[0].type === 'reload'), so no sessionStorage/localStorage flag is needed. If the type can't be determined (older browsers), Vike doesn't reload.
• If the reloaded page fails again, Vike rethrows the original error unchanged, as before.
• Production only: in development such failures are usually transform errors, which a reload doesn't fix.
• Trade-off: if hydration fails after the user manually reloaded the page, there's no automatic retry.

Tests (test/playground, production builds only):

• Entry chunk blocked on the first load: the page reloads once and becomes interactive. This test fails without the fix.
• Entry chunk blocked on every load: exactly two page loads, then the error is thrown.

Docs: new section on /deploy-sync, and an entry for it in llms.txt.

Side note: with the page proxy of @brillout/test-e2e, page.unroute() is a silent no-op (Playwright assigns this._routes, which lands on the proxy target), so the new tests route via page.context(). The existing page.unroute() call in the streamed-values test is affected too.

🤖 Generated with Claude Code

https://claude.ai/code/session_013M9XEWwcvkeKwfcC9LCwgc

[brillout]

Is the fix accurate? Do we need to make the distinction whether it's a failure upon first page load or upon client-side navigation?

[brillout-agent]

Is the fix accurate?

Yes. I reproduced the issue in test/playground (production build): when the page's entry chunk fails to load during hydration, the page stays non-interactive and the error surfaces as an unhandled rejection. With this PR, the page reloads once and becomes interactive. If the chunk keeps failing, there are exactly two page loads and then the original error is rethrown unchanged, so there's no reload loop.

Retrying the import() without reloading wouldn't work. In Chromium, the entry chunk is requested only once per page load (by the <link rel="modulepreload"> that Vike injects), and the later import() fails right away without a new request, because the browser caches the failed fetch. A reload starts from scratch, and in the new-deployment case it also gets fresh HTML.

Do we need to make the distinction whether it's a failure upon first page load or upon client-side navigation?

Yes. The recovery differs, and the code already distinguished the two cases before this PR (isFirstRender in handleErrorFetchingStaticAssets()):

• Client-side navigation (unchanged): Vike falls back to a full page load of the target URL (disableClientRouting() + redirectHard()). That page load is itself the retry, since it fetches fresh HTML and assets. It doesn't need a loop guard: it only happens upon a user navigation, and if the target page then fails to hydrate, the first-page-load logic below applies.
• First page load (what this PR changes): there's no other page to go to, so the only recovery is reloading the current page. That's the case that needs a loop guard, and it's why it uses location.reload() rather than redirectHard(): the guard checks whether the current page was loaded by a reload, and location.href = url counts as a regular navigation.

The two paths combine without looping. I checked this in the browser: a client-side navigation whose target always fails leads to a full page load, then one reload, then Vike gives up (two page loads in total).

Known limits:

• production only
• no automatic retry if the user had reloaded the page manually
• the Server Routing runtime still has no recovery; I left it out of this PR, it could be a follow-up

---

Generated by Claude Code

[brillout]

Superseded by:

• fix: improve handling when a static asset fails to load #3598