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!