Tanstack Start, React Query, deferred loading, prefetch, streaming

I have been trying to achieve deferred loading for hours now and I cannot make it work.
Basically I have /dashboard/* routes that are only accessible to authenticated users.
So in my dashboard/route.tsx layout, I prefetch in the loader without awaiting and useSuspenseQuery in the layout.
Even this simple setup doesn't work. When I look at the network tab I can see a client call the /me trpc

export const Route = createFileRoute('/dashboard')({
  component: RouteComponent,
  loader: async ({ context }) => {
    context.queryClient.prefetchQuery({
      ...context.trpc.me.queryOptions(), // this query takes 4 seconds
      staleTime: Infinity,
    })
  },
})

function RouteComponent() {
  const trpc = useTRPC()
  const { data: me } = useSuspenseQuery({
    ...trpc.me.queryOptions(),
    staleTime: Infinity,
  })

  return <div>{me.email}</div>
}

export const Route = createFileRoute('/dashboard')({
  component: RouteComponent,
  loader: async ({ context }) => {
    context.queryClient.prefetchQuery({
      ...context.trpc.me.queryOptions(), // this query takes 4 seconds
      staleTime: Infinity,
    })
  },
})

function RouteComponent() {
  const trpc = useTRPC()
  const { data: me } = useSuspenseQuery({
    ...trpc.me.queryOptions(),
    staleTime: Infinity,
  })

  return <div>{me.email}</div>
}

export const Route = createFileRoute('/dashboard')({
  component: RouteComponent,
  loader: async ({ context }) => {
    context.queryClient.prefetchQuery({
      ...context.trpc.me.queryOptions(), // this query takes 4 seconds
      staleTime: Infinity,
    })
  },
})

function RouteComponent() {
  const trpc = useTRPC()
  const { data: me } = useSuspenseQuery({
    ...trpc.me.queryOptions(),
    staleTime: Infinity,
  })

  return <div>{me.email}</div>
}

export const Route = createFileRoute('/dashboard')({
  component: RouteComponent,
  loader: async ({ context }) => {
    context.queryClient.prefetchQuery({
      ...context.trpc.me.queryOptions(), // this query takes 4 seconds
      staleTime: Infinity,
    })
  },
})

function RouteComponent() {
  const trpc = useTRPC()
  const { data: me } = useSuspenseQuery({
    ...trpc.me.queryOptions(),
    staleTime: Infinity,
  })

  return <div>{me.email}</div>
}

What I am trying to achieve is showing a loading while the query resolves.

The documentation mention NextJS but not Tanstack Start.
For example, on some NextJS documentation they say you need shouldDehydrateQuery.
Do I need it for Tanstack Start ?

const queryClient = new QueryClient({
  defaultOptions: {
    dehydrate: {
      serializeData: superjson.serialize,
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
    },
    hydrate: { deserializeData: superjson.deserialize },
    queries: {
      retry: false,
    },
  },
})

const queryClient = new QueryClient({
  defaultOptions: {
    dehydrate: {
      serializeData: superjson.serialize,
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
    },
    hydrate: { deserializeData: superjson.deserialize },
    queries: {
      retry: false,
    },
  },
})

const queryClient = new QueryClient({
  defaultOptions: {
    dehydrate: {
      serializeData: superjson.serialize,
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
    },
    hydrate: { deserializeData: superjson.deserialize },
    queries: {
      retry: false,
    },
  },
})

const queryClient = new QueryClient({
  defaultOptions: {
    dehydrate: {
      serializeData: superjson.serialize,
      shouldDehydrateQuery: (query) =>
        defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
    },
    hydrate: { deserializeData: superjson.deserialize },
    queries: {
      retry: false,
    },
  },
})

colourful-plum•4/12/25, 11:18 AM

take a look at this example https://github.com/TanStack/router/blob/af455d812f220a6df3d43dbe1610cf0d173ea092/e2e/react-start/basic-react-query/src/router.tsx

the react query plugin handles configuring the hydration / dehydration parts

GitHub

router/e2e/react-start/basic-react-query/src/router.tsx at af455d81...

Fully typesafe Router for React (and friends) w/ built-in caching, 1st class search-param APIs, client-side cache integration and isomorphic rendering. - TanStack/router

colourful-plum•4/12/25, 11:19 AM

also just a note that loaders run on the client as well so when its working you shouldn't see the network call only for the initial page load

verbal-limeOP•4/12/25, 11:28 AM

Thanks ! This is so confusing, there is a lot of examples online and they are all different

verbal-limeOP•4/12/25, 11:29 AM

for example, your link shows const queryClient = new QueryClient()const queryClient = new QueryClient()inside of createRouter.
Isn't createRouter only called once when the server starts ?
Does that mean every requests will share the same query client ? On the NextJS doc they say you need to create a new query client every request to avoid sharing cache between users

colourful-plum•4/12/25, 11:43 AM

I'm not an expert so take my input with skepticism but

createRoutercreateRouter gets called on the server during SSR for each incoming request and also on the client.

So the life of the context and query client on the server is just the length of the request and it moves to the client where the router and query cache are hydrated from the server.

I was also a little bit confused at first as there's a lot of documentation around the topic with subtle differences depending on the framework.

Ccolourful-plum also just a note that loaders run on the client as well so when its working you ...

verbal-limeOP•4/12/25, 11:43 AM

Should I see a network request immediately after the page loads ?

Ccolourful-plum I'm not an expert so take my input with skepticism **but** `createRouter` gets ...

verbal-limeOP•4/12/25, 11:44 AM

I just double-checked and you are right, createRouter gets called on every requests

colourful-plum•4/12/25, 11:45 AM

It depends on whether or not you await the fetch / prefetch and if it's a server load or client transition

colourful-plum•4/12/25, 11:45 AM

so if you await a prefetch in a route and you load that page directly, you shouldn't see the network call

colourful-plum•4/12/25, 11:45 AM

but if you navigate to it from another page you will since the loader will run on the client in that case

colourful-plum•4/12/25, 11:46 AM

maybe the await doesn't matter honestly it's hard to keep track of all these things

verbal-limeOP•4/12/25, 11:46 AM

My query takes 4 seconds to resolve.
I don't await the prefetchQuery.
The page takes 4 seconds to load.
I see another client request after the page loads that takes another 4 seconds

colourful-plum•4/12/25, 11:46 AM

I think it shouldn't matter because of the streaming the fetch should still happen on the server

colourful-plum•4/12/25, 11:47 AM

if the loader ran on the server

verbal-limeOP•4/12/25, 11:47 AM

yes it's loading fine but it not very efficient

verbal-limeOP•4/12/25, 11:48 AM

I tried staleTime: Infinity but still, the client refetch

colourful-plum•4/12/25, 11:50 AM

I'll share some relevant parts of my app where it's working as expected (confirmed await doesn't matter since it streams)

verbal-limeOP•4/12/25, 11:51 AM

Ok thank you for your help

Vverbal-lime I tried staleTime: Infinity but still, the client refetch

verbal-limeOP•4/12/25, 11:52 AM

So, I had a defaultoptions StaleTime: 0 in the createRouter and staleTime: Infinity in my layout. I thought it would override the default but apparently not

verbal-limeOP•4/12/25, 11:52 AM

so now it's working, the client doesn't refetch on load

colourful-plum•4/12/25, 11:52 AM

So in this case if I load the home page directly ie refresh I don't see a network call to the upcoming meetings query

message.txt2.58KB

colourful-plum•4/12/25, 11:53 AM

Oh nice. From what I could tell staleTime on the server didn't seem to have an effect on the query when it made it to the client

verbal-limeOP•4/12/25, 11:54 AM

ohhh

verbal-limeOP•4/12/25, 11:54 AM

they don't share default options maybe

verbal-limeOP•4/12/25, 11:54 AM

that's why

colourful-plum•4/12/25, 11:54 AM

I don't set any staletime on my query client or server query though and it is working as expected

colourful-plum•4/12/25, 11:56 AM

I'm loving the developer experience with the router and query. Super nice to be able to drill down into all your data fetching and routing stuff

verbal-limeOP•4/12/25, 11:56 AM

Yes it's really cool

verbal-limeOP•4/12/25, 11:57 AM

So now that my setup is working, time to experiement with loader. I read that if you await prefetch, the page load pauses until the prefetch is done.
And if you don't await prefetch, you can show a loader while the promise resolves

verbal-limeOP•4/12/25, 11:58 AM

with <Suspense> or <Await>

verbal-limeOP•4/12/25, 11:58 AM

I'll try

colourful-plum•4/12/25, 11:58 AM

Yep that should be how it works

colourful-plum•4/12/25, 11:58 AM

Good luck !

verbal-limeOP•4/12/25, 11:59 AM

Thanks so much for your help man

verbal-limeOP•4/12/25, 12:13 PM

Ok, awaiting or not the prefetchquery doesn't change anything, the page pauses until the loader is finished.
The example here https://tanstack.com/router/latest/docs/framework/react/guide/deferred-data-loading#deferred-data-loading-with-external-libraries doesn't work for me

Deferred Data Loading | TanStack Router React Docs

TanStack Router is designed to run loaders in parallel and wait for all of them to resolve before rendering the next route. This is great most of the time, but occasionally, you may want to show the u...

verbal-limeOP•4/12/25, 12:14 PM

Not awaiting prefetch and wrapping in suspense doesn't show the fallback

export const Route = createFileRoute('/posts/$postId')({
  // ...
  component: PostIdComponent,
})

function PostIdComponent() {
  const fastData = useSuspenseQuery(fastDataOptions())

  // do something with fastData

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SlowDataComponent />
    </Suspense>
  )
}

function SlowDataComponent() {
  const data = useSuspenseQuery(slowDataOptions())

  return <div>{data}</div>
}

export const Route = createFileRoute('/posts/$postId')({
  // ...
  component: PostIdComponent,
})

function PostIdComponent() {
  const fastData = useSuspenseQuery(fastDataOptions())

  // do something with fastData

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <SlowDataComponent />
    </Suspense>
  )
}

function SlowDataComponent() {
  const data = useSuspenseQuery(slowDataOptions())

  return <div>{data}</div>
}

verbal-limeOP•4/12/25, 12:14 PM

Maybe because I am in a layout route (dashboard.route.tsx) and not in a page route...

colourful-plum•4/12/25, 1:10 PM

Weird, I don't think that should matter tbh

Tanstack Start, React Query, deferred loading, prefetch, streaming

Similar Threads

Similar Threads

Similar Threads