Streaming Support for RR Framework mode

[GitonioDev]

Hey there i just wanted to ask if there is something to use Streaming with Tanstack Query and React Router Framework Mode (aka Remix).

[sueun-dev]

Yep, streaming is supported in TanStack Query v5 with React Router Framework Mode. The key is combining RR's defer() with selective awaiting in your loader.

The pattern

In your loader, await critical data (blocks until ready) and kick off non-critical prefetches without awaiting (these stream down as they resolve):

// app/routes/post.$id.tsx
import { defer } from 'react-router';
import { queryClient } from '~/lib/query-client';

export async function loader({ params }: Route.LoaderArgs) {
  // Critical data — await it, blocks the loader
  const post = await queryClient.fetchQuery({
    queryKey: ['post', params.id],
    queryFn: () => fetchPost(params.id),
  });

  // Non-critical — don't await, will stream
  const commentsPromise = queryClient.prefetchQuery({
    queryKey: ['comments', params.id],
    queryFn: () => fetchComments(params.id),
  });

  return defer({ post, commentsPromise });
}

On the client, wrap the deferred part in <Suspense> + <Await>:

import { Await, useLoaderData } from 'react-router';
import { useSuspenseQuery } from '@tanstack/react-query';

export default function PostPage() {
  const { post, commentsPromise } = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{post.title}</h1>

      <Suspense fallback={<p>Loading comments...</p>}>
        <Await resolve={commentsPromise}>
          <Comments postId={post.id} />
        </Await>
      </Suspense>
    </div>
  );
}

function Comments({ postId }: { postId: string }) {
  // By the time this renders, the prefetch is done (or in-flight)
  const { data } = useSuspenseQuery({
    queryKey: ['comments', postId],
    queryFn: () => fetchComments(postId),
  });

  return <ul>{data.map(c => <li key={c.id}>{c.body}</li>)}</ul>;
}

A couple of things worth knowing:

• Use fetchQuery() (not prefetchQuery()) for critical data. fetchQuery() returns data and throws errors so they surface in your errorElement. prefetchQuery() swallows errors and returns void.
• useSuspenseQuery in the <Comments> component will use the cached result from the prefetch, so it won't fire a second request.
• Add streamTimeout to entry.server.tsx to control how long the server waits before giving up on deferred promises:

// app/entry.server.tsx
export const streamTimeout = 10_000; // ms

React Router v7 shortcut

In RR v7 you can skip defer() and just return raw promises directly from the loader — RR will handle the streaming automatically:

export async function loader({ params }: Route.LoaderArgs) {
  const post = await queryClient.fetchQuery(postQuery(params.id));

  return {
    post,
    commentsPromise: queryClient.prefetchQuery(commentsQuery(params.id)),
  };
}

Optional: experimental_prefetchInRender

If you want queries to start fetching during render rather than waiting for effects, enable this in your QueryClient:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { experimental_prefetchInRender: true },
  },
});

This is experimental and opt-in, but it can improve perceived performance in SSR scenarios.

The TanStack Query Advanced Server Rendering guide and the React Router Suspense guide both cover this in detail. There's also a working React Router example in the TanStack repo.

[GitonioDev]

Wow! i did not know that!

1. Question: Who handles the HydrationBoundary here i thought i need after the <Await/> component to use another <HydrationBoundary/> or will after RR Awaits the promise add the data to the global useMatches() so it will just catch it on the global useDehydratedState() hook and Hydrate the result

2. Question: Do I need to use the useSuspenseQuery hook or can I also use useQuery because the docs say they don't recommend using useQuery

[sueun-dev]

Great questions!

1. HydrationBoundary with deferred data

Short answer: the global useDehydratedState() via useMatches() won't automatically pick up your deferred query data.

Here's why: useDehydratedState() reads from the serialized loader data at initial render time. When you use defer(), those values are still Promises at that point, so they're not included in the dehydrated state that gets sent in the initial HTML payload. The dehydrate(queryClient) call captures the cache snapshot before the deferred queries resolve, so the deferred data simply isn't there.

But here's the good news: you don't need a separate <HydrationBoundary> inside <Await> for this pattern. Since the deferred data is behind a <Suspense> boundary, the server sends the fallback markup (e.g., "Loading comments...") for that section. When the client hydrates, it sees the same fallback, so there's no hydration mismatch. Then useSuspenseQuery fires on the client, fetches the data, and renders the comments.

So the flow is:

1. Server sends initial HTML with the Suspense fallback for deferred content
2. Client hydrates, sees the same fallback (no mismatch)
3. useSuspenseQuery kicks in on the client, fetches the comments, renders them

The "extra" client fetch is totally fine here because this is non-critical deferred data anyway. That's the whole point of deferring it.

Note: TanStack Router has built-in streaming hydration that handles this automatically, but React Router's defer()/<Await> is a different mechanism and doesn't have that integration with TanStack Query. So don't worry if you see TanStack Router docs talking about automatic streaming dehydration, that's a different setup.

2. useSuspenseQuery vs useQuery

useSuspenseQuery is the right call here, and here's why:

• useSuspenseQuery throws a Promise when data isn't ready, which is what triggers the <Suspense> boundary to show its fallback. useQuery doesn't do this. It just returns { isLoading: true, data: undefined } and renders immediately.

• So if you swap in useQuery, your <Suspense> boundary basically does nothing. You'd need to handle the loading state yourself with if (isLoading) return <Spinner /> inside the component. It works, but you're duplicating what Suspense already does for you.

• The other big advantage: with useSuspenseQuery, data is always defined (never undefined). No need for null checks or optional chaining. With useQuery, data is T | undefined and you have to guard against it.

• Error handling is different too. useSuspenseQuery throws errors up to the nearest <ErrorBoundary>. useQuery gives you isError and error fields you check manually.

Quick comparison:

// useSuspenseQuery — Suspense handles loading, ErrorBoundary handles errors
function Comments({ postId }) {
  const { data } = useSuspenseQuery(commentsQuery(postId));
  // data is always defined here
  return <ul>{data.map(c => <li key={c.id}>{c.body}</li>)}</ul>;
}

// useQuery — you handle loading/error yourself
function Comments({ postId }) {
  const { data, isLoading, error } = useQuery(commentsQuery(postId));
  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;
  return <ul>{data.map(c => <li key={c.id}>{c.body}</li>)}</ul>;
}

Both work, but useSuspenseQuery is the better fit when you're already using <Suspense> and <Await>. It keeps loading/error state management out of your component and in the boundary where it belongs.

One small caveat: useQuery has the enabled option (useful for conditional fetching), but useSuspenseQuery doesn't support it. If you ever need to conditionally skip a query, that's the one case where useQuery is the better choice.

Hope that clears things up! Let me know if anything's still unclear.

[GitonioDev]

1. Question: But why i need Streaming at all? I can just use the useSuspenseQuery for non critical data always without Streaming the data

This is what the React Router docs show for Streaming
<Await resolve={nonCriticalData}> {(value) => <h3>Non critical value: {value}</h3>} </Await>

so they basically use {(value) =>xxx} to access the streamed value why not do:

<Await resolve={commentsPromise}> {(comments) => <HydrationBoundary state={comments}><MyComponentWithQueryInside></HydrationBoundary>} </Await>

wouldnt this avoid an extra client fetch because the data that got streamed in will be Hydrated into Tanstack Query cache

2 Question: Does Tanstack Router / Start also do that extra client fetch or what? (Basically can i achieve the same thing as Tanstack Router / Start as with React Router Framework)