Why use jotai-tanstack-query?

[tylersayshi]

I was going to post this on https://github.com/jotaijs/jotai-tanstack-query , but there is no discussion board over there.

A question about using Jotai with react query:

jotai-tanstack-query seems specifically targeted at using atoms as deps for the queryKey field docs

How is this first snippet better/different from the second?

with jotai-tanstack-query:

const idAtom = atom(1)
const userAtom = atomWithQuery((get) => ({
  queryKey: ['users', get(idAtom)],
  queryFn: async ({ queryKey: [, id] }) => {
    const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
    return res.json()
  },
}))
const useUserQuery = () => useAtom(userAtom)

const UserData = () => {
  const [{ data, isPending, isError }] = useUserQuery()

With using @tanstack/react-query directly:

const idAtom = atom(1)
const useUserQuery = () => {
  const [userId] = useAtom(idAtom)
  // from @tanstack/react-query
  return useQuery({
    queryKey: ['users', userId],
    queryFn: async ({ queryKey: [, id] }) => {
      const res = await fetch(`https://jsonplaceholder.typicode.com/users/${id}`)
      return res.json()
    },
  })
}

const UserData = () => {
  const { data, isPending, isError } = useUserQuery()

Asking this because it feels like I am missing something. If it is just a matter of DX/ergonomics (I get that), but I am specifically interested in if there are other considerations for why to create that extension.

Thanks for any feedback in advance

[tylersayshi]

Follow up: If I wanted to go in the opposite direction, a tanstack query result that I wanted to store as a derived atom, how would I do that.

Specifically this might be useful if I have a really large piece of async state stored in a react-query result that I want to derive transformations and pieces from.

const { isPending, isError, data, error } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodoList,
})

// how do I properly get "first two todos" stored in an atom derived from `data` here?

[dai-shi]

I would like to hear from @kalijonn , but my perspective is jotai-tanstack-query is pure atom model, which is not tied to React. It depends only on tanstack/query-core.

[dai-shi]

fyi, my general stance is: https://blog.axlight.com/posts/you-might-not-need-react-query-for-jotai/

[kalijonn]

I felt like this needed some explanation and some examples, so I wrote about this.

https://blog.thiskali.com/jotai-tanstack-query/

You can use @tanstack/react-query with jotai, without using jotai-tanstack-query. I believe jotai-tanstack-query has far better DX when the state is intertwined.

About the follow up question, you have to use useEffect and setAtom to get tanstack query's result into an atom.

[dmaskasky]

About the follow up question, you have to use useEffect and setAtom to get tanstack query's result into an atom.

A pure jotai solution here could be to use jotai-effect.

[tylersayshi]

Thanks, thats helpful! I could then use jotai-tanstack-query to hold the query state as an atom that I could that get inside a jotai-effect to make the final derivation if it were from react-query 🤔

[dmaskasky]

import { withAtomEffect } from 'jotai-effect'
import { QueryObserver, queryOptions } from '@tanstack/react-query'
import { queryClientAtom } from 'jotai-tanstack-query'

const studentsOptions = queryOptions({
  queryKey: ['students'],
  queryFn: async () => {
    const response = await fetchStudents()
      if (response.status !== 200) {
        throw response.body
      }
      return response.body
  })
})
const observer = new QueryObserver(queryClient, studentsOptions)
const studentsAtom = withAtomEffect<Student[] | null>(
  atom<Student[] | null>(null),
  (get, set) => {
    const queryClient = get(queryClientAtom)
    const data = queryClient.getQueryData(studentsOptions.queryKey)
    if (data) {
      set(studentsAtom, data)
    }
    return observer.subscribe(result => {
      if (result.data) {
        set(studentsAtom, result.data)
      }
    });
  }
)

[kalijonn]

I could then use jotai-tanstack-query to hold the query state as an atom that I could that get inside a jotai-effect to make the final derivation if it were from react-query

I'm not sure if you're talking about 2 different scenarios, one with jotai-tanstack-query and one without but with @tanstack/react-query. Just wanted to clarify that if you're using jotai-tanstack-query, you don't need jotai-effect if you only want some derivation of that data.

const getStudents = ():<{name:string, age:string}[]> => {
  return []
}

const studentsDataAtom = atomWithQuery(() => ({
  queryKey: ['users'],
  queryFn: getStudents,
}))

const studentNamesAtom = atom((get) => {
  const { data, isPending, isError } = get(studentsDataAtom)
  if (isPending) return []
  if (isError) return []
  return data.map((d) => d.name)
})

tangent: @dmaskasky Why can't I find withAtomEffect here: https://jotai.org/docs/extensions/effect ? This api feels more intuitive than mounting effects in atom's read function.

[dmaskasky]

@kalijonn the withAtomEffect api is brand new, I haven't had time to update the docs on the website yet, but the README is up-to-date.

I like withAtomEffect more too because most of my use cases are to update a single atom when something changes.

[dmaskasky]

I've given a lot of thought to this question over the past several months, I'll try my best to describe my thoughts on this that I hope complement @kalijonn's blog post. I'm also curious what others have to say on the topic.

@tanstack/query-* could be an atomic state management system.

I ran into the following probem: when two components both use an inline useQuery that share the same queryKey but returns or throws different values in their queryFn. In this case TypeScript will misrepresent the types of data and error of one of the two useQuery calls.

Please consider the following:

function ComponentA() {
  const { data, error } = useQuery({
    queryKey: ['students'],
    queryFn: async () => {
      const response = await fetchStudents()
      if (response.status !== 200) {
        throw response.body
      }
      return response.body
  })
  ...
}

function ComponentB() {
  const { data, error } = useQuery({
    queryKey: ['students'],
    queryFn: async () => {
      const response = await fetchStudents()
      if (response.status !== 200) {
        throw new Error('Unable to fetch students')
      }
      return response.body.students
  })
  ...
}

What is the type of data and error? In ComponentA, it is typeof response.body and typeof response.body. In ComponentB, it is typeof response.body.students and Error class instance. But they both can't be right, right? Since ComponentA and ComponentB share the same QueryClient instance, their actual type (not the one TypeScript reports) will depend on whichever component runs first, and first after invalidateQueries invocation for ['students']. This is a problem. Local changes should not cause global breaking side-effects. We must centralize.

To solve this problem I considered many solutions:

• custom hooks
• query key factory
• overloading the typescript interface

Eventually I settled on centralizing the query options object. Even better is that @tanstack/query-react supports this pattern with the query options utility!

import { queryOptions } from '@tanstack/react-query'

function studentsOptions() {
  return queryOptions({
    queryKey: ['students'],
    queryFn: async () => {
      const response = await fetchStudents()
      if (response.status !== 200) {
        throw response.body
      }
      return response.body
  })
}

A few observations of this pattern:

1. QueryClient is a sort of global store
2. Query Options defines what data it accesses with the queryKey
3. Query Options defines the type of the data with queryFn

Query Options looks a lot like jotai atoms. Interesting.

@tanstack/query-* idiomatic main difference with jotai - colocation

Whether you centralize on hooks, queryOptions, queryKeys, or you choose not to centralize; tanstack query uses the co-location pattern. The individual components that call useQuery are treated separately with some handwaving that the logic for a given queryKey is considered the same across the app. Colocation allows component props to be integrated locally into the business logic, while the handwaving allows us to cheat and pretend its valid everywhere. This hack makes the ergonomics of tanstack query very easy, but it means that tanstack query isn't truely a global state management solution. We need another hack to make it compatible with jotai.

function Student({ id }: { id: number }) {
  const { data } = useQuery({
    queryKey: ['student', { id }],
    queryFn: ({ queryKey }) => {
      const response = await fetchStudent({ id: queryKey[1].id })
      if (response.status !== 200) {
        throw response.body
      }
      return response.body
  })
  ...
}

How would you pair colocation with jotai-tanstack-query?

Despite the fundamental difference, there are a few ways to handle this:

1. atomFamily

import { atomFamily } from 'jotai/utils';
import { atomWithQuery } from 'jotai-tanstack-query';

const studentAtomFamily = atomFamily((id) => atomWithQuery({
  queryKey: ['student', id],
  queryFn: ({ queryKey }) => {
    const response = await fetchStudent({ id: queryKey[1].id })
    if (response.status !== 200) {
      throw response.body
    }
    return response.body
  },
}));

function StudentComponent({ id }) {
  const [studentData, { isLoading, error }] = useAtom(studentAtomFamily(id));
  ...
};

TODO: errors thrown in an atomFamily should propagate to QueryErrorResetBoundary.

2. ScopeProvider

import { atomFamily } from 'jotai/utils';
import { atomWithQuery } from 'jotai-tanstack-query';

const studentIdAtom = atom(null);

atomWithQuery((get) => {
  const id = get(studentIdAtom)
  return  {
    queryKey: ['student', id],
    queryFn: ({ queryKey }) => {
      const response = await fetchStudent({ id: queryKey[1].id })
      if (response.status !== 200) {
        throw response.body
      }
      return response.body
    },
  }
});

function StudentBaseComponent({ id }: { id: number }) {
  const store = useStore()
  useMemo(() => {
    store.set(studentIdAtom, id)
  }, [store, id])
  const [studentData, { isLoading, error }] = useAtom(studentIdAtom);
  ...
};

function StudentComponent({ id }: { id: number }) {
  return (
    <ScopeProvider atoms={[studentIdAtom]}>
      <StudentBaseComponent key={id} id={id} />
    </ScopeProvider>
  );
};

3. Do you really need to pass id as a prop?
   When using jotai + tanstack query in your app, you really only need to pass props to specify variants of a react component. Props such as id can be considered client-side state, instead of a variant, so you could just store it in an atom instead. If everything is in an atom, then you don't really need to worry about the difference between tanstack query's colocation pattern and jotai's atom centralization.

[kalijonn]

Inline useQuery has always bothered me so much for that same reason. I always defined query options separately as a variable and imported that into components to be used by the useQuery.

About variants:
If you're using tanstack/query, you don't need any special way to handle variants. There's 2 scenarios for variants.

1. You have 2 or more variants mounted at the same time. Imagine 2 widgets that show weather for 2 different cities mounted at the same time.
2. You always have a single variant mounted at the same time. Think an atom that gets page level data. Like a blog post with comments/like etc.

It might seem like atomFamily might be a good use case for both. In both the cases we're trying to avoid refetching visited pages/variants. And in trying to do that, we're using atomFamily like a cache to hold the data for those variants. This is great if you're NOT using tanstack/query. Below is how I would do it when using tanstack/query.

1. To mount multiple variants at the same time, you only need a create/get atom pattern to create multiple atoms (jotai-tanstack-query atoms). The data is cached in tanstack/query's cache to avoid refetching.
2. When there's always a single atom mounted at a time, we don't even need the create/get atom pattern. You can store the identified (postId) in an atom and use that in you jotai-tanstack-query atom. When you navigate back to already visited posts, this data should already be in the cache avoiding refetching.

In both cases, what I'm tring to do is use tanstack/query's QueryCache as the cache instead of using atomFamily's internal WeakMap as a cache.

atomFamily still works because the atoms within that family are subscribed to the changes (invalidation/background refetch etc). It's just that you don't need it.

[dmaskasky]

Regarding centralizing the queryOptions, I really like this pattern where omitting params gives a default response.

function selfAssign(fn) {
  return Object.assign(fn, fn())
}

// returns the current user if id is omitted
const userQueryOptions = selfAssign((id?: number) => {
  return queryOption({
    queryKey: ['user', id],
    queryFn: fetchUser(id),
  })
})

const { data: currUser } = useQuery(userQueryOption)
const { data: userFour } = useQuery(userQueryOptions(4))

Of course to do this you'd have to patch @tanstack/query-core since they don't allow function options by default.

[dai-shi]

#2730 (reply in thread)

is this the sort of thing that would make sense to package up as its own extension?

@tylerlaws0n Hm, no. Setting atom values in useEffect (or atomEffect) is the thing I want to avoid the most. It's valid, but it's a last resort.

[dmaskasky]

I just read the source for jotai-tanstack-query.

@kalijonn I think it is the current behavior today that if the queryAtom shares the same queryKey as a useQuery, when the data is fetched initially by the useQuery, and not the queryAtom, for the queryAtom to listen to changes and still be reactive. Then a derived atom can just get the query atom and form the derived data, like in the example below. Is this correct?

Then I don't think we need atomEffect or useEffect to synchronize data for storing derived data.

import { queryOptions } from '@tanstack/react-query'
import { atomWithQuery } from 'jotai-tanstack-query'

const studentsQueryOptions = queryOptions({
  queryKey: ['students'],
  queryFn: fetchStudents,
})

const studentsQueryAtom = atomWithQuery(studentsQueryOptions)

// derived atom reads from studentsQueryAtom
// but data was originally fetched from the useQuery
const studentNamesAtom = atom((get) => {
  const { data: students } from get(studentsQueryAtom)
  return students.map(getStudentName)
})

function Component() {
  const { data } = useQuery(studentQueryOptions)
  ...
}

[kalijonn]

I saw this after commenting this: #2730 (reply in thread)

I agree, if the idea is only to derive, we don't need jotai-effect.

[tylersayshi]

To follow up on this tweet from tkdodo: https://x.com/TkDodo/status/1835240510102868169

I think the concept of "derived state" is not practically solved by storing the entire app state as atoms. Sure, you can use jotai-tanstack-query then can create a derived atom with this pattern, but what if your derived state depends on state in the url as tkdodo mentions? (this is exactly my use case)

I think I'd rather have react as the common ground where state that depends on multiple sources (jotai, url state, react query, etc?) for where to perform the derivation. This is why I react for a solution like this:

const makeUseDerivedAtom = <Args extends any[], Derived>(
  fn: (...args: Args) => Derived
): ((...args: Args) => Derived) => {
  const dAtom = atom<Derived>();

  return (...args: Args): Derived => {
    const [derivedState, setDerivedState] = useAtom(dAtom);

    useEffect(() => {
      setDerivedState(fn(...args));
    }, args);

    return derivedState!;
  };
};

const useRepeatedName = makeUseDerivedAtom((start: number, name: string) =>
  `${name}\n`.repeat(start)
);

const nameRepeated = useRepeatedName(someNumber, router.params.name)

I can see how it would be nice to use jotai-tanstack-query if my derivations were only the product of other atoms as state, but the introduction of other sources, like the url or localStorage makes me want to solve this in a useEffect.

The alternative would be to mirror the url state as atoms as well, so that they are available with the atom get method. Keeping the url state atoms in sync with the url and making this work with any router/library combination sounds unnecessary when we can just create an atom from a useEffect.

I fully agree with this from Dai-shi:

Setting atom values in useEffect (or atomEffect) is the thing I want to avoid the most. It's valid, but it's a last resort.

That being said, in the interest of keeping complexity to a minimum, while getting the benefits of a single derived atom, I think useEffect + atom might be the best solution for me.

[dai-shi]

I think I'd rather have react as the common ground where state that depends on multiple sources (jotai, url state, react query, etc?) for where to perform the derivation.

My mental model is the opposite.
React is good to render things, but not to manage state. React Compiler might be a solution it the future, but for now, we need to memoize all derived states to avoid extra re-renders.
Jotai is to solve the issue with lifting up all non-local states in atoms. It solves the memoization issue with dependency tracking.

The alternative would be to mirror the url state as atoms as well

https://github.com/jotaijs/jotai-location is the one, and atomWithHash is a cool one.
Unfortunately, the lack of the maintainer holds this library back a bit.

[dmaskasky]

The main issue with atomWithLocation, atomWithHash is that it doesn't listen to changes to the location. It works if you treat the atom, not the url, as the source of truth.

[dai-shi]

atomWithHash does listen to the changes of hash.
For other parts, It's simply the lack of DOM capability.
It has to be combined with frameworks, which is annoying.

[tylersayshi]

Just wanna clarify this a bit:

I think I'd rather have react as the common ground where state that depends on multiple sources (jotai, url state, react query, etc?) for where to perform the derivation.

I didn't mean react as the place to store or memoize the derivation. I fully agree with this:

React is good to render things, but not to manage state. React Compiler might be a solution it the future, but for now, we need to memoize all derived states to avoid extra re-renders.

For my initial point about react being the common ground for where state can depend on multiple sources, I mean that I'd like a common place where I trigger the update of my memoized state. NOT: to use react to store that derivation

The specific scenario I am thinking of is one where we use nuqs to manage url query param state and want to use this state to derive partial data from a react-query result. To Dai-shi's point: It is definitely best to memo-ize this outside of the scope of react (a jotai atom is perfect).

That being said, I do not want to also mirror my nuqs state inside jotai atoms just to be able to make this derivation. So a useEffect that depends on changes from my nuqs state and react-query state seems simplest to me.