Optional Suspense Support in React-Query Hooks

[sulhadin]

Description

In the recent versions of react-query, the ability to set suspense: true | false is deprecated, requiring the use of useSuspenseQuery for suspense-enabled queries. This change poses a challenge in scenarios where suspense needs to be optional.

Steps to reproduce

In our current implementation, each API call is linked to a single React-Query hook, encapsulated within a function. This function can be invoked from multiple components. However, not all of these components require or support suspense.

Expected behavior

The ideal solution would allow a single query hook to dynamically handle both suspense and non-suspense scenarios without duplicating requests or hooks.

Current Workaround

Currently, it seems necessary to duplicate each request: one using useQuery and another using useSuspenseQuery. This approach is not optimal, as it leads to redundant code and potential maintenance issues.

Question

Is there an alternative approach or best practice to handle this scenario where suspense can be optionally applied within the same query hook, depending on the component it is used in?

Additional Context from Recent PR

I noticed that the removal of suspense as a configurable option seems to be a workaround taken from this PR: 6ee06719aedbf210d9c336b039f40b9667de4da0. This PR may provide some background on the current issue and decision-making process.

TanStack Query version

5.17.8

TypeScript version

4.8.3

[TkDodo]

you pretty much want this:

const todosQuery = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos
})

then use it in components as you like:

useSuspenseQuery(todosQuery)
useQuery(todosQuery)

[sulhadin]

As mentioned in my previous problem, I want to avoid duplicating code throughout my project. My project heavily relies on Suspense, specifically on every useQuery.

For instance, consider a function that encapsulates useQuery, as demonstrated in the usage below:

function Component() {
  const { data } = UserQuery.useGetUser(); // Assuming Suspense is set to true, like in traditional use.

  return (
    <>{data.userName}</>
  );
}

export default Component;

This component can be used anywhere the username is needed. Wherever I use this component, I can wrap it with a Suspense block:

<Suspense fallback={<>Loading...</>}>
  <Component />
</Suspense>

However, there might be cases where I call UserQuery.useGetUser(); inside a custom hook:

function useCustomHook() {
  const { data } = UserQuery.useGetUser(); // Assuming Suspense is set to true, like in traditional use.
  // ... some logic
  // ... get result

  return { result };
}

export default useCustomHook;

In this scenario, I might not want useGetUser to be suspended, as a component that calls useCustomHook might already be suspended.

With the solution you suggest, I could implement the functionality like this:

// In the UserQuery class.
...
function useGetUser(suspense = true) {
  const todosQuery = queryOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos
  });

  return suspense ? useSuspenseQuery(todosQuery) : useQuery(todosQuery);
}

This solution seems a bit like a workaround, especially since the react-query library previously supported making Suspense optional.

Assuming I have around a hundred API calls where Suspense is set to true by default, should I refactor all of them? @TkDodo

[TkDodo]

With the solution you suggest, I could implement the functionality like this:

that wasn't really my suggestion. It was more like:

const userQuery = queryOptions({
  queryKey: ['user'],
  queryFn: fetchUser
});

function Component() {
  // no need to assume suspense because it's clearly visible
  const { data } = useSuspenseQuery(userQuery)
  return (
    <>{data.userName}</>
  );
}

function useCustomHook() {
  // also no need to assume suspense is off
  const { data } = useQuery(userQuery)

  return { result };
}

Can you make two custom hooks useUser and useSuspenseUser? Sure, if you want. For these cases though, I find calling useQuery / useSuspenseQuery directly in a component fine.

especially since the react-query library previously supported making Suspense optional.

Note that suspense was always explicitly labelled as an experimental feature, because suspense for data fetching from react itself was also experimental. We've been quite clear about that in the docs: https://tanstack.com/query/v4/docs/react/guides/suspense

NOTE: Suspense mode for React Query is experimental, same as Suspense for data fetching itself. These APIs WILL change and should not be used in production unless you lock both your React and React Query versions to patch-level versions that are compatible with each other.

Now we do break the API (not in a minor or patch but in a major), so please don't be upset because it "was supported before and now isn't".

We changed the API because suspense is an architectural change, and way more than a flag that turns on a global loading spinner. In the future, we might want to integrate with a first class suspense cache from react or the use hook. We can do that better if suspense is a separate API rather than a flag.

[sulhadin]

Thank you for your quick response 🙂

I do not include useQuery explicitly in my custom hooks. They remain utils inside another workspace. Apparently, I will solve this with an optional parameter. 😥