RFC: QueryStrictMode for Prefetching

[TkDodo]

Prefetching is hard, but it’s also one of the best ways to get data to your users as fast as possible. There are also multiple ways to prefetch, the most common ones are:

• on the server: with server-side-rendering or fetching in server components, we can seed the cache before the component renders on the client.
• in route loaders: in an SPA, the route loader is probably as high-up in the tree as possible.
• in a root component with usePrefetchQuery
• in event handlers with queryClient.prefetchQuery

Prefetching or “hoisting your data requirements” is especially recommended when using suspense, because it can easily trigger request waterfalls: Calling useSuspenseQuery twice in the same component gives you a waterfall. Calling it in siblings within the sam suspense boundary almost gave us a waterfall in React19.

The problem

The main problem we are seeing with prefetching is code-dislocation. Just calling useSuspenseQuery in your component and having it work is very convenient, but without a compiler like relay, it won’t be possible to extract those data requirements and trigger prefetching somewhere else automatically.

So what we are left with is duplicating what we do: Have a component call useSuspenseQuery with certain options, and use the same options in your route loader or event handler to do prefetching. That’s an okay trade-off, however, it comes with two additional problems:

Under-prefetching

Let’s say we write a component that fetches from /issues/$id , so we add prefetching for that to our route loader. Everything is fine and we ship it. Next, someone else adds fetching comments for that issue to the component, so there will be a new query that fetches from /issues/$id/comments. It’s quite common to forget to add that fetch to the route loader, which leaves us with a new request waterfall: We are only stating to fetch comments after we are done fetching the issue details, even though they could load in parallel.

Over-prefetching

On the flip-side, let’s assume we do prefetch issue details and comments correctly in the route loader, but then, we decide to move comments to an entirely different page. When the component moves, so does the query, but the prefetching in the route loader might stay. That will fire an unnecessary request for /issues/$id/comments , and it might even block the page from loading until that request is done.

Proposed solution

To address both problems, the idea is to introduce a <QueryStrictMode> component in DEV mode only (similar to the React StrictMode component) that will do the following:

• Whenever useSuspenseQuery would suspend the component with a new promise, it would log an error. This will alert developers that they are using a suspense query, but haven’t prefetched it. When the component renders, it should merely pick up a promise that is already in the cache. This would address the under-prefetching issue.
• Whenever a Query isn’t used within a given time frame (probably 5ish seconds?) after it has been prefetched, an error will be logged. This will alert developers that they have prefetched something that could be unnecessary. This would address the over-prefetching issue.

Potentially, we could make this component’s logger customisable (defaulting to console.error) so that you can opt out of logging for certain queries:

<QueryStrictMode
  logger={
    (props: { type: 'prefech-missing' | 'unnecessary-prefetch', message: string, query: Query }) =>
      console.error(message)
  }
>
{ children }
</QueryStrictMode>

Implementation details

Under-prefetching protection is relatively simple to implement: We can check before we throw fetchOptimistic if there is a promise in the cache already. If not, fetchOptimistic would trigger the fetch, which isn’t really what we want.

Over-prefetching protection is a bit more involved. I think we could subscribe to the QueryCache directly, and whenever a fetch starts while there is no active observer for the given key, we consider it a prefetch (note to self: we have to ignore while we’re in isRestoring mode because restores from an external storage shouldn’t be considered prefetches). Then, we start a timer which we can cancel as soon as an observer subscribes or the query gets garbage collected.

[TkDodo]

@Ephem one open question that came to my mind today is how this would integrate with the planned experimental_prefetchInRender flag combined with the React.use() operator. I don't think we can warn here as well when the prefetchInRender fires a fetch, as it would make the whole feature obsolete: If you have a running promise already, you will never need to fetch-in-render...

[jquense]

Excited that RQ is thinking about this! We've been working on our own enforcement of this on top but it'd be nice to have it built in.

One concern with the Context provider approach is that it makes it harder to do incremental migrations of existing code. In our experience you rarely have nice and neat "clear" branches of the app you can cordon off to enforce prefetching in. In practice we pull up queries one at a time as we have time to track down requests in component trees and refactor fetching logic out of hooks so they can be prefetched by the router. This can take some time before we can say "don't allow fetching in render here".

One option is to have something like usePrefetchedQuer(y|ies) (or query option) that marks individual call sites as always expecting data for the under prefetching cases.

[TkDodo]

that marks individual call sites as always expecting data

that really is useSuspenseQuery to me. If you useSuspenseQuery without prefetching, you will have waterfalls as soon as you have more than one query.

[jquense]

I don't disagree with that. My point is more that we already have large app with suspense queries and waterfalls we want to remove, If we wrap them all in QueryStrictMode, the logs will just be noise, and errors unhelpful, until we can add prefetching for each of them.

I do also think there are cases where you intentionally want a waterfall still want to use suspense to manage loading behavior, but i'm less confident about that use case.

[TkDodo]

got it. that's where I was thinking that you can customize the logger to ignore certain "known waterfalls".

I don't think we should make a hook that says "I need a prefetch to have happened here":

function Component() {
  useThisShouldBePrefeteched(todoOptions)

  const { data } = useSuspenseQuery(todoOptions)
}

because that would be an opt-in behaviour on a per-use-case basis. (Almost) no one would do that. Imagine the exhaustive-deps lint rule to only scream at you when you say "I want this deps to be exhaustive". Not good.

If you know that you need prefetching in a certain place, you are already far ahead of the curve. At this point, you can call usePrefetchQuery somewhere higher up the tree, too. Most people don't know that they get waterfalls when they write useSuspenseQuery, and that's where the QueryStrictMode is valuable: To avoid them being introduced accidentally.

[akrynski-1]

Will there be support for regular useQuery? It might not create as bad waterfalls as useSuspenseQuery but it still makes a difference when data is prefetched in route loaders, especially with lazy loading. There could be an option for that as some queries might be non-prefetchable for various reasons.

[TkDodo]

Would you have an idea how we could support that? How should we or the user decide which queries should warn?

[akrynski-1]

Maybe something like this, but with less ugly name:

const { data } = useQuery({ ..., warnIfNotPrefetched: true })

It could even be false by default, user would still be able to change this when creating QueryClient instance, by using defaultOptions. It could be adjusted per query level when needed using code above.