Understanding offline example

[cflorez10]

I was reviewing the offline example in docs, and I have two questions:

• what is the idea of a persistor?
• what role does the cache and the persistor play when they work together?

[TkDodo]

• persisters persist the QueryCache to an external store like localstorage
• the cache has your queries, and the persister writes your cache to the external storage. Then, when the page is loaded, assuming you use the PersistQueryClientProvider, the cache will be filled with data from the external storage.

[inquiztr]

I am also trying to understand the concept and if it is suitable for my situation:
User adds a product to cart, and react-query would store the 'cart' in localstorage.
User navigates to shopping cart page (new page/refresh) and rather than getting the cart again from api call, I would use the localstorage data to render the cart.
Is this the proper use case for persistors?
What if it bypassed Persistors entirely, and manually retrieve localstorage myself and injected into react-query's 'initialData' property?

[TkDodo]

The persisters mirror the local query cache. When a user adds a cart to a product, you would make a mutation that would store it in the backend, would you not?

If there is also a query for that resource then that will be mirrored to localstorage. If the user refreshes the page, yes, then it will be rehydrated from localstorage. A background refresh (api call) might or might not occur then depending on the set staleTime.

What if it bypassed Persistors entirely, and manually retrieve localstorage myself and injected into react-query's 'initialData' property?

You can do that, but it's more work to wire up. You also have no auto-syncing to localstorage, and you can get into race conditions if you render your app while you restore from localstorage. Granted, localstorage is synchronous so that would work, but it wouldn't work with storages that are async, like localforage or indexDB.

Those things are solved with the persisters.

[inquiztr]

Thank you @TkDodo. That clears it up for me nicely.
Yes there would be a mutation on add to cart, and the response returns the updated cart object which I will persist to improve next page's user experience (while a proper refresh happens in the background).
I am excited to add RQ to our app and all the UX improvements it can bring.
Thank you for clearing it up for me.

[dohomi]

Thanks for some clarifications @TkDodo thats really helpful. I have one more question about the PersistQueryClientProvider and its livespan as I could not find it yet. For my app I use localstorage with following setup:

export const tanstackQueryClient = new QueryClient({
    defaultOptions: {
        queries: {
            retry: false,
            refetchOnWindowFocus: false,
            cacheTime: 1000 * 60 * 60 * 24, // 24 hours,
            staleTime: 1000 * 60 * 60 * 2, // 1 hour
        }
    }
})

const localStoragePersister = createSyncStoragePersister({
    storage: typeof window !== 'undefined' ? window.localStorage : undefined,
})    

export function ReactQueryProvider({children}: PropsWithChildren) {
    return (
        <PersistQueryClientProvider
            client={tanstackQueryClient}
            persistOptions={{
                persister: localStoragePersister
            }}
        >
            {children}
            <ReactQueryDevtools
                initialIsOpen={false}/>
        </PersistQueryClientProvider>
    )
}

The app is an PWA with offline state and I need to make sure that some of the query data must be infinite available even when a device is offline for a couple of days.

Which of the values of react-query is responsible to ensure that always localstorage data is being used fallback? Or is that how the PersistQueryClientProvider works by default?

[TkDodo]

There is nothing that uses localStorage as "fallback". The QueryClient is synced with localStorage - what you have in memory, you'll also have in localStorage.

cacheTime decides when unused queries are removed from the cache, and thus, also removed from localStorage. So set this to a high enough value.

Also, the persisters additionally have a maxAge option, after which the content of the storage will be deemed "too old to use". Set this higher as well.

[dohomi]

There is nothing that uses localStorage as "fallback". The QueryClient is synced with localStorage - what you have in memory, you'll also have in localStorage.

cacheTime decides when unused queries are removed from the cache, and thus, also removed from localStorage. So set this to a high enough value.

Also, the persisters additionally have a maxAge option, after which the content of the storage will be deemed "too old to use". Set this higher as well.

This is super helpful, thanks for pointing this out. If I set the maxAge of persister to 1 week and the cacheTime to 24h, when the device does not have internet for 2 days would the data be available through the persister? Is it recommended to keep both props at the same value?

How does the the staleTime would affect the data in offline state? Lets say I set staleTime to 0(I always want most recent data) and the device goes offline for the 2 days during a field research, will the cacheTime make sure (I set this value to 1 week), that the data will be available the entire time?

Thanks for taking the time to clarify my questions!

[TkDodo]

If I set the maxAge of persister to 1 week and the cacheTime to 24h, when the device does not have internet for 2 days would the data be available through the persister? Is it recommended to keep both props at the same value?

If your App is running even though you don't have network connection and the Query in question is unused (= has no active observers via useQuery), what will happen after 24h is that it is garbage collected, and because the persister is always a 1:1 representation of what you have in-memory, it will also be removed from the external storage.

We might have something like what you're looking for coming in v5:

• feat: fine grained storage persister #5125

How does the the staleTime would affect the data in offline state? Lets say I set staleTime to 0(I always want most recent data) and the device goes offline for the 2 days during a field research, will the cacheTime make sure (I set this value to 1 week), that the data will be available the entire time?

staleTime has nothing to do with evicting data from the cache. If cacheTime is set to one week, yes, you will have data available for the entire time if you have successfully fetched it once.

[dohomi]

Great that clears up all questions. I will upgrade to v5 beta soon, I have it on my roadmap

[ddennis]

Offline mutations when no onSuccess callback

Sorry if this is not the correct place to ask, ill be happy to move it.
Looking at the mutation from the Offline example which i have also pasted underneath for reference.

For a online version i would add the onSuccess callback to handle side effects like navigating to prev or next page.
But since the onSuccess is never called when user is offline i am unsure where to place side effects.

I have attempted placing it in a useEffect, but it feels dirty and causes problems when the onSuccess handler is called when coming back online. My use case is a questionnaire with multiple questions and i would like to navigate to the next question based on its id.

useEffect(() => {
    if ((assignment.isIdle === false && assignment.isPaused) || assignment.isSuccess) {
            const assignment = assignment.context
            const nextQuestion = assignment.questions[1]
           // navigate to next page 
    }
  }, [updateAssignments.isIdle, updateAssignments.isPaused, updateAssignments.isSuccess])

  const updateMovie = useMutation({
    mutationKey: movieKeys.detail(movieId),
    onMutate: async () => {
      await queryClient.cancelQueries({ queryKey: movieKeys.detail(movieId) })
      const previousData = queryClient.getQueryData(movieKeys.detail(movieId))

      // remove local state so that server state is taken instead
      setComment(undefined)
      queryClient.setQueryData(movieKeys.detail(movieId), { ...   })
      return { previousData }
    },
    onError: (_, __, context) => {
      queryClient.setQueryData(movieKeys.detail(movieId), context.previousData)
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: movieKeys.detail(movieId) })
    },
  })

Thanks in advance.

[TkDodo]

if you can and want to navigate to the next page without actually having done the mutation (often, the result of the mutation determines where to go next, which is why onSuccess is often the right place), then yes, I think you need a useEffect, or render a <Navigate to="..." /> component (if your router exposes something like that), which is often just a wrapper around useEffect. We don't currently expose an onPaused callback because it was never needed

[ddennis]

@TkDodo Thanks for answering.

Sorry if i was not clear. I was hoping there would be a clear way to handle side effects when offline. Without the useEffect.

I did find your blog post: https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose
Based on your answer and the blog post, my impression is that i should evaluate the updateMovie const updateMovie = useMutation(...) and do side effects in a useEffect/Navigate hook

Could you correct me if i am wrong? or if possible please point me in a better direction?

Some thoughts
The "onPaused"/"onSettled" makes sense in my head, since it indicates if the request did not complete and lets me decide if i want to let the user continue of wait for an online state. From my test neither onSeattled or onSuccess are being called while offline.

What i am looking for:
I would like to wait for the completion if the user is online, but if the user is offline. I am willing to trust the cache mutation in onMutate.
But i can't figure out where to place the logic i want to perform after the mutation, since the action is based on the result of the mutation.

[TkDodo]

and do side effects in a useEffect/Navigate hook

my blogpost only covers useQuery, where the callbacks have been removed. It has nothing to do with useMutation, and I'd still use the callbacks on useMutation.

The "onPaused"/"onSettled" makes sense in my head

yeah, onPaused / onContinue doesn't currently exist. It's a trade-off between having everything available during rendering and for side-effects and balancing this with the api surface, which can get quite large if we do this.

I would like to wait for the completion if the user is online, but if the user is offline. I am willing to trust the cache mutation in onMutate.

then I'd put the redirect in onSuccess of the mutate callback for the online case, and for the offline case, I'd do the useEffect for now.