How to prevent oversized IndexedDB cache with persistQueryClient?

[wandering-sage]

We’re using IndexedDB to persist the React Query client in a large app with many API calls and data-heavy views.

A common case in our app is fetching work item records on a list view. These are paginated, but over time, a user could fetch up to a million items if they dedicatedly fetch all the pages. After typical usage, the cache grows to ~4k queries (~45MB). We are worried that with an extended usage, this could go up to ~20k queries (~250MB) or even more.
This raises concerns about poor user experience, performance, and potential quota limits on browser storage.

To mitigate this, we’re currently capping the number of queries we restore from IndexedDB to 10k.

restoreClient: async () => {
  const MAX_QUERIES_TO_RESTORE = 10000;
  const cachedClient = await storage.getItem(idbValidKey);

  if (cachedClient.clientState?.queries?.length > MAX_QUERIES_TO_RESTORE) {
    cachedClient.clientState.queries = cachedClient.clientState.queries.slice(0, MAX_QUERIES_TO_RESTORE);
  }

  return cachedClient;
}

But this feels like a hack because:

• It doesn’t consider total size — a few large queries can blow past storage limits even before hitting the 10k count.
• Mutating the restored queryClient directly might cause issues with React Query internals or might have unintended consequences.

Question:
👉 Is this kind of restore-time capping something you’d recommend?
Or is there a safer, preferred way to handle cache bloat with persistence?

Also curious, would it be possible to introduce a size-based limit in addition to maxAge when persisting or restoring from IndexedDB?

We imagine a config like:

persistQueryClient({
  maxAge: 1000 * 60 * 60 * 24, // 24 hours
  maxSize: 100 * 1024 * 1024 // 100 MB cap
})

Thanks for the amazing work on this library! We’re happy to contribute more context or explore a PR if this is something that fits the roadmap.

[TkDodo]

the size limit usually comes from the storage itself. We also wouldn’t know what to do if he size gets exceeded.

if you’re worried that it grows too large, you can:

• limit what you persist - it doesn’t have to be the whole cache
• set a shorter gcTime to remove things that aren’t used for some time
• implement retries to handle errors upon writing to the cache, e.g. if the size limit of the storage is exceeded. We have a removeOldestQuery strategy where the oldest query gets removed before another write is attempted.