Skip to content
Source
Sign inSign up
TanStack/router

data-only route mounts a second pendingComponent after hydration when pendingMinMs is set #8640

Send to my agent
OpenTarekkharsa(GitHub profile, opens in a new tab) opened this issue 4 comments

Which project does this relate to?

Router

Describe the bug

A route with ssr: 'data-only' and a pendingComponent server-renders the pending component, and the client hydrates it. When pendingMinMs (or defaultPendingMinMs) is set, React then hides the hydrated pending component and mounts a second copy from the route's Suspense fallback. The page holds two pending components, one with display: none, and any animation in the pending UI restarts.

Cause, as I read main (663282b0e):

  1. matchView renders a data-only match as <ClientOnly fallback={pendingElement}>{<MatchInner />}</ClientOnly>, so the server HTML is the pending element.
  2. hydrate() presents the boundary as status: 'pending'. offerPending finds a presented pending match with no session and starts pendingMinMs from now ("conservatively start pendingMinMs from now"), so the match stays pending for at least that long.
  3. After hydration, ClientOnly switches from fallback to children. MatchInner sees status === 'pending' with a live router._tx and throws router._tx[5].
  4. That update is not a transition, so React hides the already-mounted primary content (the hydrated pending element) and mounts the Suspense fallback: a second pendingElement.

With pendingMinMs: 0 the transaction has usually finished before ClientOnly switches, so nothing suspends. The bug needs the match to still be pending when ClientOnly switches, and pendingMinMs makes that certain.

Complete minimal reproducer

https://github.com/Tarekkharsa/tanstack-router-hydration-pending-min-repro

Steps to Reproduce the Bug

pnpm i
pnpm test   # builds, serves with vite preview on 7302, runs Playwright; exits 1

The test loads /dashboard (ssr: 'data-only', instant loader, pendingComponent renders <div data-skeleton>) three times per scenario. It records every distinct [data-skeleton] element and when the content appears:

FAIL pendingMinMs=400, route chunk delay 0 ms, run 1: skeleton elements 2, ref attaches 2, most in the DOM at once 2 (1 visible), content at 617 ms
FAIL pendingMinMs=400, route chunk delay 0 ms, run 2: skeleton elements 2, ref attaches 2, most in the DOM at once 2 (1 visible), content at 474 ms
FAIL pendingMinMs=400, route chunk delay 0 ms, run 3: skeleton elements 2, ref attaches 2, most in the DOM at once 2 (1 visible), content at 472 ms
ok   pendingMinMs=0,   route chunk delay 0 ms:   skeleton elements 1, content at ~60 ms   (3/3)
ok   pendingMinMs=0,   route chunk delay 300 ms: skeleton elements 1, content at ~320 ms  (3/3)
3/9 loads mounted a second skeleton

I get the same result with packages packed from main at 663282b0e.

Expected behavior

The server-rendered pending component is the only one. It stays mounted until the route content replaces it.

Screenshots or Videos

No response

Platform

  • Router / Start Version: @tanstack/react-router 1.170.41, @tanstack/router-core 1.171.34, @tanstack/react-start 1.168.60; also main at 663282b0e
  • OS: macOS
  • Browser: Chromium (Playwright 1.62.1)
  • Browser Version: 151.0.7922.34
  • Bundler: vite
  • Bundler Version: 8.3.1

Additional context

A possible fix. While the match is pending, render the pending element in ClientOnly's children slot too. The element then has the same type at the same position before and after hydration, so React keeps the hydrated node:

   if (resolvedNoSsr) {
-    content = <ClientOnly fallback={pendingElement}>{content}</ClientOnly>
+    content = (
+      <ClientOnly fallback={pendingElement}>
+        {match.status === 'pending' ? pendingElement : content}
+      </ClientOnly>
+    )
   }

With that change built from main, the reproducer passes 9/9 with one skeleton element on every load. I have only tried React; Solid and Vue wrap data-only matches in ClientOnly too.

A related question. After hydration, pendingMinMs still holds the loaded content for about 400 ms (content at ~450 ms against ~50 ms without the minimum). The pending UI has been on screen since first paint, so counting the minimum from navigation start instead of from hydrate() would keep its purpose and avoid most of the hold. The current comment says the choice is conservative on purpose, so I'm asking rather than calling it a bug.

We hit this in a production Start app. We work around it by running the first document with defaultPendingMinMs: 0 and restoring it on the first onRendered.

I'm happy to open a PR with an SSR-then-hydrate regression test if this direction looks right.

  1. A related question. After hydration, pendingMinMs still holds the loaded content for about 400 ms (content at ~450 ms against ~50 ms without the minimum). The pending UI has been on screen since first paint, so counting the minimum from navigation start instead of from hydrate() would keep its purpose and avoid most of the hold. The current comment says the choice is conservative on purpose, so I'm asking rather than calling it a bug.

    Can you open a separate issue (if there isn't one already) for this? i'm aware of this, but just never made it a priority

  2. Thanks for #8643. I opened #8648 for the hold after hydration.

    While measuring it on main I found a second problem, now #8647: with pendingMinMs: 0 on the client, a no-SSR route logs a React hydration mismatch on a hard load. The client load commits before React hydrates the route's Suspense boundary, and MatchInner renders the content against the server's pending HTML. A copy of the #8640 React test with pendingMinMs: 0 passes before #8643 and fails 5 of 8 cases after it; Solid and Vue pass. It matters for the delay too, because a shorter hold produces the same timing. Both issues have the measurements and a change I tried.

  3. AI disclosure: Claude (Opus) investigated this and wrote this comment.

    Another data point: we hit this with pendingMinMs: 0. The minimum isn't required; the match only has to still be pending when ClientOnly switches, and a slow beforeLoad or loader does that on its own.

    Our setup is a TanStack Start app with an ssr: false layout route that has pendingComponent, pendingMs: 0, pendingMinMs: 0, a beforeLoad that resolves the session over the network and a loader that preloads data. That takes about a second, well past hydration. The pending component has a CSS progress bar, so the second copy shows up as the bar running partway, then dropping back to empty and starting over.

    Measured on the production build, desktop Chrome, warm cache, with a MutationObserver injected ahead of the app's scripts:

    • 131 ms: the server-rendered pending element appears
    • 350 ms: it gets display: none and a second copy mounts
    • 1,426 ms: the route content replaces it

    In dev, the second copy's CSS animation had currentTime 0 while the first had run about 1 s.

    Versions: @tanstack/react-router 1.170.45, @tanstack/router-core 1.171.38, @tanstack/react-start 1.169.3, React 19.3.1.

    As we read #8649, it covers this case too, since MatchInner no longer suspends over pending UI rendered in place, but we haven't tested it. Until a fix ships, we hand the CSS animation's startTime from the hydrated copy to the new one through a ref callback and the Web Animations API, so the bar carries on.

Sign in to join this conversation.