PersistedQueryClientProvider causing UI freeze in react native

[alimurad-1]

Hi, I have been trying to implement query persistence in my react native app made with expo.

The issue I am facing is that the UI freezes for 2 to 3 seconds when user opens the app and it blocks the navigation as well.

This is my HOC for the persistence provider:

const ALLOWED_QUERY_KEYS = [
  'agent',
  'fetch-user-stories',
  'users',
  'userCurrency',
  'groupCurrency',
  'posts',
  'currency',
  'projects',
  'agency-stories',
  'storyCount',
  'settings',
];


const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,


});


export const PersistedQueryProvider = ({
  children,
  queryClient,
  onHydrated,
}: PersistedQueryProviderProps) => {
  const [isHydrated, setIsHydrated] = useState(false);


  const handleSuccess = () => {
    setIsHydrated(true);
    onHydrated?.();
  };


  const handleError = async () => {
    try {
      await asyncStoragePersister.removeClient();
    } catch (e) {
      captureError(e);
    }


    setIsHydrated(true);
    onHydrated?.();
  };


  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{
        persister: asyncStoragePersister,
        maxAge: 1000 * 60 * 60 * 24,
        dehydrateOptions: {
          shouldDehydrateQuery: query => {
            try {
              const { queryKey } = query;


              if (!queryKey || !Array.isArray(queryKey) || queryKey.length === 0) {
                return false;
              }
              const [firstKey] = queryKey;


              if (typeof firstKey !== 'string') {
                return false;
              }


              return ALLOWED_QUERY_KEYS.includes(firstKey);
            } catch (error) {
              captureError(error);


              return false;
            }
          },
        },
      }}
      onSuccess={handleSuccess}
      onError={handleError}
    >
      {isHydrated ? children : <View />}
    </PersistQueryClientProvider>
  );
};
[//package.json](https://package.json/)

"react-native": "0.77.3",
"expo": "^52.0.0",
"@tanstack/react-query": "^5.87.4",
"@tanstack/react-query-persist-client": "^5.90.12",
"@react-native-async-storage/async-storage": "1.23.1",

[TkDodo]

hard to say without a runnable reproduction

[alimurad-1]

Unfortunately I can't really do a repo for this one, the app is pretty large and relies on some internal API endpoints that I can't expose publicly.

[krishparmar22242]

This is a common performance bottleneck in React Native when using AsyncStorage with TanStack Query. The 2-3 second UI freeze happens because AsyncStorage is relatively slow, and once the data is retrieved, the JavaScript thread has to synchronously parse a potentially large JSON string of your cache, which blocks the UI.

Here are the most effective ways to solve this, ranked from the "Proper Fix" to optimization steps.

1. The "Proper" Fix: Switch to MMKV
   AsyncStorage uses the old "bridge" in React Native, which is slow for large data sets. The industry standard for performance is react-native-mmkv. It is significantly faster because it uses JSI (JavaScript Interface) to read/write data synchronously.
   Why this fixes the freeze: MMKV allows the persister to access the storage without the overhead of the asynchronous bridge, preventing the thread lock-up.
   The Solution:
   Install MMKV: npx expo install react-native-mmkv
   Update your persister:

import { MMKV } from 'react-native-mmkv';

const storage = new MMKV();

const mmkvStorage = {
  setItem: (key, value) => {
    storage.set(key, value);
  },
  getItem: (key) => {
    const value = storage.getString(key);
    return value === undefined ? null : value;
  },
  removeItem: (key) => {
    storage.delete(key);
  },
};

const asyncStoragePersister = createAsyncStoragePersister({
  storage: mmkvStorage,
});

2. Add a throttleTime to the Persister
   If your app is making many small updates, the persister might be trying to write to the storage too frequently, which impacts the JS thread's ability to handle navigation and UI updates.
   The Fix: Add a throttleTime (e.g., 1000ms) to your persister config to batch the writes.

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
  throttleTime: 1000, // Writes to disk only once per second
});

3. Check the Payload Size of 'posts' and 'projects'
   You are persisting keys like posts and projects. If these queries contain hundreds of items with large image URLs or metadata, your persisted JSON string could be several megabytes. Parsing a 5MB JSON string on a mobile JS thread will always cause a freeze.
   The Fix: Use gcTime (formerly cacheTime) to ensure old data is cleared frequently, or refine your shouldDehydrateQuery to avoid persisting large, non-essential data lists.

4. Implementation Logic Check
   In your HOC, you are conditionally rendering {isHydrated ? children : }. While this is good for preventing the app from seeing empty states, it doesn't stop the underlying thread lock-up.
   If you switch to MMKV as suggested in Step 1, you will likely see that 2-3 second freeze disappear entirely, as the "read" becomes nearly instantaneous.

If this switch to MMKV helps unfreeze your UI and navigation, please consider marking this as the accepted answer so it can help other Expo/React Native developers!

[alimurad-1]

@krishparmar22242 Thanks for the detailed reply. In order to use the latest MMKV version I had to move to new arch. We were already migrating our app to new arch and when I moved persistence to the new arch it was fast enough even without using MMKV.

[alimurad-1]

But I have another challenge! is there any way I can modify ALLOWED_QUERY_KEYS so that it persists just the specific api instead of persisting every api that contains the query key. For example, now every query that has 'posts' in its query key will be persisted.

[krishparmar22242]

Regarding your challenge of making persistence more granular, you are currently using a "Broad Match" strategy. To target specific APIs instead of every query containing a key, you should move away from a simple string list and use Query Meta or Exact Key Matching.

Here are the two best ways to achieve that granular control:

1. The "Cleanest" Way: Using Query Metadata (Recommended)
   Instead of maintaining a manual list of strings in your HOC, you can "tag" specific queries for persistence directly where you define them. TanStack Query provides a meta object for exactly this purpose.
   How to implement it:
   Tag your query:
   When you call useQuery, add a persist flag to the meta property.

useQuery({
  queryKey: ['posts', 'list'],
  queryFn: fetchPosts,
  meta: {
    persist: true, // Only this specific call will be persisted
  },
});

Update your HOC logic:
Change your shouldDehydrateQuery to look for that specific meta flag.

dehydrateOptions: {
  shouldDehydrateQuery: (query) => {
    // Only persist if the 'persist' flag is explicitly true in meta
    return query.meta?.persist === true;
  },
},

2. The "Exact Match" Way: Using Array Comparison
   If you don't want to use metadata and prefer keeping the list in your HOC, you need to check for the full query key structure instead of just the first string.
   Update your HOC logic:

const EXACT_ALLOWED_KEYS = [
  ['posts', 'featured'], // Persists ['posts', 'featured'] but NOT ['posts', 'all']
  ['settings'],
  ['agent', 'profile', 'v1'],
];

// ... inside PersistedQueryProvider ...
dehydrateOptions: {
  shouldDehydrateQuery: (query) => {
    return EXACT_ALLOWED_KEYS.some((allowedKey) => 
      // Compare the full array length and values
      query.queryKey.length === allowedKey.length &&
      query.queryKey.every((value, index) => value === allowedKey[index])
    );
  },
},

Since you are already on the New Architecture, using the Meta approach is the great move. It keeps your code clean and ensures that your storage (AsyncStorage or otherwise) only handles exactly what you intend, preventing unnecessary disk I/O.

If this metadata strategy helps you gain full control over your API persistence, please consider marking this as the accepted answer to help other React Native developers!

[alimurad-1]

Once again thanks for another detailed answer. Really appreciate it. Can I use meta tags with PersistedQueryClientProvider and what is the difference between import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'; and import { persistQueryClient } from "react-query/persistQueryClient-experimental";

With in my current setup I am unable to persist queries using the meta approach.

[PALLAVIKHEDLE]

I’d recommend using meta + shouldDehydrateQuery instead of matching on parts of the query key. It’s more flexible and easier to maintain as keys change.
useQuery({ queryKey: ['user', id], queryFn, meta: { persist: true }, })
shouldDehydrateQuery: (q) => q.meta?.persist === true
2. PersistQueryClientProvider vs persistQueryClient
They ultimately do the same thing - the difference is mainly ergonomics:

PersistQueryClientProvider: declarative, React-friendly, recommended for most apps

persistQueryClient: lower-level, useful if you need to wire persistence outside React or control lifecycle manually

[ismaildasci]

the UI freeze happens because AsyncStorage is slow and blocks the main thread during hydration.

few things to try:

1. use MMKV instead of AsyncStorage (much faster):

pnpm add react-native-mmkv

import { MMKV } from "react-native-mmkv"

const storage = new MMKV()

const mmkvPersister = {
  setItem: (key, value) => storage.set(key, value),
  getItem: key => storage.getString(key) ?? null,
  removeItem: key => storage.delete(key),
}

2. or defer hydration with InteractionManager:

useEffect(() => {
  InteractionManager.runAfterInteractions(() => {
    // start hydration here
  })
}, [])

3. reduce persisted data - you have many keys. try keeping only critical ones:

const ALLOWED_QUERY_KEYS = ["agent", "users", "settings"]

4. show splash screen during hydration instead of empty View:

{isHydrated ? children : <SplashScreen />}

MMKV is the best fix, its synchronous and much faster than AsyncStorage