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