Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Zustand persist middleware loses state or shows defaults in React Native

Errorpersisted state is empty after restart

Short answer

With AsyncStorage the store hydrates after the first render, so the app briefly shows default values. Wrap AsyncStorage in createJSONStorage, give each store a unique name, and wait for hydration before reading state. A changed version number also discards old saved data unless you migrate.

  • Applies to zustand 5, React Native 0.76+, @react-native-async-storage/async-storage 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the store after startup and again a second later. If the second print has your data, it is hydration timing. If not, it is storage, name or version.

    console.log(useBoundStore.persist.hasHydrated(), useBoundStore.getState());
    setTimeout(() => console.log(useBoundStore.persist.hasHydrated(), useBoundStore.getState()), 1000);
  2. 2Match what you see, then jump to its fix

    1. 1The first render shows defaults, then the saved values appear.Async storage hydrates after the first renderFix
    2. 2State is kept in a web build but not on the phone.storage is not set to AsyncStorageFix
    3. 3One store overwrites another, or some fields reset while others stay.Two stores share one name, or partialize leaves fields outFix
    4. 4Data disappears right after an app update that changed the store shape.The version changed and old data is ignoredFix

What does the error look like?

  • persisted state is empty after restart
  • store shows default values on first render
  • logged out for a moment on app start

Cause 1 of 4

Async storage hydrates after the first render

1Check

With asynchronous storage such as AsyncStorage, the store is not hydrated at the initial render. hasHydrated() reports false at first.

grep -n "persist(" -r src/

2Fix

Track hydration in the store and show a loading state until it finishes.

export const useBoundStore = create()(
  persist(
    (set) => ({ _hasHydrated: false, token: null }),
    {
      name: 'auth-storage',
      storage: createJSONStorage(() => AsyncStorage),
      onRehydrateStorage: () => () => {
        useBoundStore.setState({ _hasHydrated: true });
      },
    },
  ),
);

3Verify

On cold start the loading state shows, then the saved values.

# kill the app and open it again

Confirmed by zustand.docs.pmnd.rs

Did this fix it?

Cause 2 of 4

storage is not set to AsyncStorage

1Check

The default storage is localStorage. React Native needs another engine passed through createJSONStorage.

grep -n "createJSONStorage" -r src/

2Fix

Set storage to AsyncStorage wrapped with createJSONStorage.

// Expo: npx expo install @react-native-async-storage/async-storage
import AsyncStorage from '@react-native-async-storage/async-storage';
import { persist, createJSONStorage } from 'zustand/middleware';

persist(stateCreator, {
  name: 'app-storage',
  storage: createJSONStorage(() => AsyncStorage),
});

3Verify

Change state, kill and reopen the app. The values remain.

# after reopening, log useBoundStore.getState()

Confirmed by zustand.docs.pmnd.rs

Did this fix it?

Cause 3 of 4

Two stores share one name, or partialize leaves fields out

1Check

name is the storage key and must be unique per store. partialize picks which fields are saved; by default the whole state is.

grep -n "name:\|partialize" -r src/

2Fix

Give every persisted store its own name and list the fields you want saved.

persist(stateCreator, {
  name: 'cart-storage',
  storage: createJSONStorage(() => AsyncStorage),
  partialize: (state) => ({ items: state.items }),
});

3Verify

Change both stores and reopen the app. Each keeps its own values.

# log both stores after restart

Confirmed by zustand.docs.pmnd.rs

Did this fix it?

Cause 4 of 4

The version changed and old data is ignored

1Check

If the stored version does not match version (default 0), the stored value is not used.

grep -n "version:\|migrate" -r src/

2Fix

Raise version when you change the shape and add a migrate function that returns state for the current version.

persist(stateCreator, {
  name: 'app-storage',
  version: 1,
  storage: createJSONStorage(() => AsyncStorage),
  migrate: (persisted, version) => {
    if (version === 0) {
      return { ...persisted, fullName: persisted.name };
    }
    return persisted;
  },
});

3Verify

Install the old build, save data, install the new one. The data is still there.

# upgrade the app without clearing storage

Confirmed by zustand.docs.pmnd.rs

Did this fix it?

How do I stop it coming back?

  • Wait for hydration before routing on persisted values such as a login token.
  • Use a unique name for each store.
  • Bump version and write migrate whenever the stored shape changes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.