Is it safe to use experimental_prefetchInRender: true?

[kalkv]

We just started implementing Suspense on some views. In the majority of cases, we can use useSuspenseQuery for our queries since they are fetching initial and crucial data. But some of the queries we use simultaneously are dependent on certain conditions — i.e., we won't always have authenticated user data, because we don't always require authentication.

The perfect solution for keeping Suspense applied for loading states and preserving possibly undefined data in conditionally enabled queries is to use React.use conditionally together with the promise returned from useQuery. Unfortunately, it turned out that this feature is still experimental.

Is it generally safe to use this experimental feature at this stage without concerns about the experimental useQuery behavior breaking the logic or behaving unpredictably?

Also, what's the current status? How is it developing, and what direction is it heading in at the moment?

[kalkv]

@harshagarwalnyu Thanks for the answer.

@TkDodo Are you able to confirm above? I found your comment with your thoughts about the feature nowadays and I'm afraid that you have changed your mind regarding this and the flag in general.

[chrisjcthomas]

The experimental_prefetchInRender: true feature flag allows you to access a stable .promise property on the result object returned by useQuery. This promise can then be passed to React.use(result.promise) to conditionally suspend components when data is loading.

Is it safe to use?

• API Stability: Since it is prefixed with experimental_, the API is not stable. The location or naming of the .promise property could change in minor or patch releases, meaning it is not recommended for production unless you pin your exact @tanstack/react-query version.
• Behavioral Quirks: It can trigger unexpected refetches or duplicate invocations under React's Strict Mode (which renders components twice in development). It also has known compatibility issues with useQueries and certain error boundaries.
• SSR Caution: While relatively safe for Client-Side Rendering (CSR), it has edge cases during Server-Side Rendering (SSR) where streaming HTML might not suspend or resume exactly as intended.

The Recommended Alternative:

If you need conditional Suspense behavior in a stable, production-grade manner, the TanStack team recommends either:

1. Using useSuspenseQuery directly for queries that should always suspend.
2. For conditionally enabled queries, prefetching the data on the server or route level using queryClient.prefetchQuery() before rendering, rather than trying to resolve promises conditionally during the render phase.