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,
  },
})

[esteban389]

Can we update the indexdb example on the docs to this? I recently had a similar problem and ended up copying the asyncThrottle func into my project 🫠

[TkDodo]

sure, please file a PR

[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

[LinkdJulioFlores]

I made this for offline first experience: https://github.com/LinkdJulioFlores/LinkdJulioFlores-tanstack-start-offline-first-pwa

[barry166]

Your setup is close, but I would change two things for a real offline PWA.

First, use IndexedDB instead of localStorage for this amount of data; persistence is still the right mechanism, but localStorage will block the main thread and gets painful with large tables. Second, don't call invalidateQueries() unconditionally in onSuccess if the app may start offline — that marks restored data stale and immediately tries to refetch.

The usual pattern is: set maxAge and gcTime longer than your expected offline window, prefetch required queries while online with queryClient.prefetchQuery(...), persist with an IndexedDB persister, then only invalidate after you know you're online again. Also keep query keys stable and avoid persisting huge derived UI data if it can be rebuilt from smaller cached API responses.