Help with Configuring TanStack Query for Offline Mode in PWA

[WojakGra]

I'm currently working on app with PWA that needs to support offline access to data using TanStack Query. I’ve already set up a persister, but I’m unsure about the best practices for configuring it to ensure that all necessary queries are available offline — especially for use cases where a user might open the app the next day without internet access and still expect full functionality.

A few specific questions I have:

• How should I configure the persister to ensure that queries are properly saved and restored across sessions?
• Is there a recommended way to manually prefetch and persist queries, so that I can ensure certain data is available offline ahead of time?
• Are there any common pitfalls or limitations I should be aware of when using TanStack Query in offline-first scenarios?

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 60 * 24 * 3,
      gcTime: 1000 * 60 * 60 * 24 * 14,
      networkMode: 'offlineFirst',
      refetchOnWindowFocus: false,
      refetchOnReconnect: false,
      refetchOnMount: false,
      retryOnMount: false,
    },
    mutations: {
      networkMode: 'offlineFirst',
    },
  },
})



const persister = createAsyncStoragePersister({
  storage: window.localStorage,
  key: 'xxxxxxxxxx',
  retry: removeOldestQuery,
  serialize: (data) => compress(JSON.stringify(data)),
  deserialize: (raw) => {
    try {
      if (!raw) {
        return undefined
      }
      const str = decompress(raw) || raw
      return JSON.parse(str)
    } catch {
      return undefined
    }
  },
})



return (
  <PersistQueryClientProvider
    client={queryClient}
    persistOptions={{ persister, maxAge: 1000 * 60 * 60 * 24 * 14 }}
    onSuccess={() => {
      queryClient.resumePausedMutations().then(() => {
        queryClient.invalidateQueries()
      })
    }}
  >
    {children}
    <ReactQueryDevtools />
  </PersistQueryClientProvider>
)

[TkDodo]

Please be more specific with your question. What about the code you showed isn’t working for you?

[WojakGra]

I would like to be sure that all the data I have downloaded will remain in the browser and will be displayed in the application in, say, two days. Is the code I have a good solution, or is there something better? The thing is, the application will be available offline as a PWA (I still need to spend some time here to get the PWA working, because something isn't loading :D).

[WojakGra]

Or maybe use something like this From 0 to Production: How I Built a Fully Offline-First PWA in React

[TkDodo]

will remain in the browser and will be displayed in the application in, say, two days.

yes, it will.

[WojakGra]

@TkDodo Is it possible to create by you guys, out-of-the-box persister that uses IndexedDB.
I had a problem with performance and the second i changed from localStorage to IndexedDB the app was way faster by the example here.

The problem was, when i hade a ~15k rows (rows with children) send to client into expandable table with virtualization.

Layout:
Root -> 1 level -> 2 level -> 3 level -> 4 level
1 rows -> ~50 rows -> ~500 rows -> ~10000 rows

[TkDodo]

you can use indexDB just fine with our persisters? We also have nothing specific to localStorage, so I’m not sure what you’re talking about.

you can do this:

import { get, set, del } from 'idb-keyval'

const persister = createAsyncStoragePersister({
  storage: {
    getItem: get,
    setItem: set,
    removeItem: del,
  },
})

[WojakGra]

Example of IndexedDB persister - https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient#building-a-persister

Example of localStorage in async persister - https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient#persistqueryclientprovider