Deferred loader's background update triggers fallback? (Example Updated)

[Redbird10]

Hi, I'm noticing that when using a deferred loader with Suspense, if the data becomes stale (even though the immediate cached value is available), the deferred part still triggers the Suspense fallback during background updates. The documentation suggests that cached values should be used immediately and updated in the background without causing a fallback.

Has anyone else encountered this issue, or does anyone have best practices to avoid this fallback flash during background updates?

[schiller-manuel]

can you please provide a complete minimal example that shows this?

[Redbird10]

Sure, I've provided an example with description below.

[Redbird10]

Here's a link to the minimal example:
https://stackblitz.com/edit/github-ztsdyhzq?file=src%2Froutes%2Ftime.tsx

Description:
I'm experiencing an issue with deferred loaders in TanStack Router. When data becomes stale and the loader updates in the background, the deferred loading part triggers the Suspense fallback. I would expect the cached immediate data to remain visible while the deferred data updates silently in the background, similar to the behavior of normal (non-deferred) loading.

Steps to Reproduce:

1. Navigate to the Time tab.
2. In the loader, the non-deferred time is awaited for 2 seconds, while the deferred time is returned without awaiting.
3. Observe that the non-deferred time is rendered after 2 seconds when the loader resolves, and the deferred part remains in a pending state for another 2 seconds, which is expected.
4. Navigate to the Home tab and back to the Time tab to invalidate the loader.
5. Observe that the stale non-deferred time is shown from the cache, and a background update begins.
6. After 2 seconds, the updated loader data returns, and the non-deferred time is refreshed.
7. However, while the deferred promise is still pending, the Suspense fallback ("Loading updated time...") appears instead of showing the cached value.

Any insights or best practices to avoid this unnecessary fallback render would be greatly appreciated. Thanks!

[AhmedBaset]

and the deferred part remains in a pending state for another 2 seconds, which is expected.

No, the deferred part should remain pending for 4 seconds. The deferred promise doesn't start until the fast one resolves, because you await the fast promise in the loader.

For your question, the Suspense fallback is rendered because the loader creates a new Promise every time it runs. React Suspense sees a completely new promise in the "pending" state, so it renders fallback

If React sees the same resolved promise, it won't show the fallback

let promise: Promise<string> | null = null;

export const Route = createFileRoute('/time')({
  loader: async () => {
   
   const deferred =
      promise ?? // use a cached promise
      new Promise<string>((resolve) => {
        setTimeout(() => {
          resolve(new Date().toLocaleTimeString());
        }, 4000);
      });

    if (!promise) {
      promise = deferred;
      console.log('INITILIZING A NEW PROMISE...');
    } else {
      console.log("GOT FROM THE CACHE")
    }

    return { fast, deferred };
  },
  component: TimeComponent,
});

[Redbird10]

Thanks for pointing out the timing. You're right that the deferred part starts only after the awaited part resolves.

That said, I think this specific workaround doesn’t quite address the issue I'm describing, which is around refreshing stale data.

In your example, the deferred promise is cached and reused, so it never actually refreshes. That avoids the fallback, but also prevents the deferred data from updating, which isn’t the desired behavior when the data is stale.

Deferred loading is meant to improve UX by allowing non-blocking initial renders. But it shouldn’t regress from standard loading behavior. With normal loading, stale data remains visible during background updates, and the new value swaps in once it's ready. If deferred loading falls back to a loading state again during updates, the added disruption can outweigh the UX benefits it was meant to provide.

So I’m wondering if there’s a recommended way to solve that?

[AhmedBaset]

I wasn't trying to solve the issue just explaining why