react-native-mmkv

To use MMKV as a persistence layer for TanStack Query (react-query), you need to install the necessary persistence packages, create a compatible storage adapter, and wrap your application with PersistQueryClientProvider.

1. Install dependencies

Install the async storage persister and the persist client packages:

yarn add @tanstack/query-async-storage-persister @tanstack/react-query-persist-client

2. Create the MMKV storage adapter

Since react-query expects an Async Storage-like interface, create a clientStorage object that maps setItem, getItem, and removeItem to MMKV methods. Note that getItem must return null instead of undefined to be compatible.

3. Configure the PersistQueryClientProvider

Use the created clientPersister within the persistOptions prop of the PersistQueryClientProvider in your root component.

import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
import { createMMKV } from "react-native-mmkv"
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'

// 1. Initialize MMKV
const storage = createMMKV();

// 2. Create the adapter
const clientStorage = {
  setItem: (key, value) => {
    storage.set(key, value);
  },
  getItem: (key) => {
    const value = storage.getString(key);
    return value === undefined ? null : value;
  },
  removeItem: (key) => {
    storage.remove(key);
  },
};

// 3. Create the persister
export const clientPersister = createAsyncStoragePersister({ storage: clientStorage });

// 4. Use in your App
const App = () => {
  return (
    <PersistQueryClientProvider persistOptions={{ persister: clientPersister }}>
      {/* Your App Content */}
    </PersistQueryClientProvider>
  );
};

To use react-native-mmkv as the storage engine for Zustand's persist middleware, you must create a StateStorage object that maps Zustand's storage interface to MMKV's methods.

1. Create an MMKV instance using createMMKV().
2. Implement the StateStorage interface with setItem, getItem, and removeItem.
3. Use storage.set(name, value) for setItem.
4. Use storage.getString(name) for getItem, ensuring you return null if the value is undefined.
5. Use storage.remove(name) for removeItem.

import { StateStorage } from 'zustand/middleware'
import { createMMKV } from 'react-native-mmkv'

const storage = createMMKV()

const zustandStorage: StateStorage = {
  setItem: (name, value) => {
    return storage.set(name, value)
  },
  getItem: (name) => {
    const value = storage.getString(name)
    return value ?? null
  },
  removeItem: (name) => {
    return storage.remove(name)
  },
}

To persist Jotai atoms using MMKV, you must implement a custom atomWithMMKV function. This function leverages Jotai's atomWithStorage and createJSONStorage utilities, wrapping MMKV's getString, set, remove, and addOnValueChangedListener methods.

createJSONStorage automatically handles JSON.stringify() when saving and JSON.parse() when retrieving values, allowing you to store complex objects directly.

Once implemented, use atomWithMMKV(key, initialValue) instead of the standard atom(initialValue) to ensure the state persists across app restarts.

import { atomWithStorage, createJSONStorage } from 'jotai/utils';
import { createMMKV } from 'react-native-mmkv';

const storage = createMMKV();

function getItem(key: string): string | null {
  const value = storage.getString(key)
  return value ? value : null
}

function setItem(key: string, value: string): void {
  storage.set(key, value)
}

function removeItem(key: string): void {
  storage.remove(key);
}

function subscribe(
  key: string,
  callback: (value: string | null) => void
): () => void {
  const listener = (changedKey: string) => {
    if (changedKey === key) {
      callback(getItem(key))
    }
  }

  const { remove } = storage.addOnValueChangedListener(listener)

  return () => {
    remove()
  }
}

export const atomWithMMKV = <T>(key: string, initialValue: T) =>
  atomWithStorage<T>(
    key,
    initialValue,
    createJSONStorage<T>(() => ({
      getItem,
      setItem,
      removeItem,
      subscribe,
    })),
    { getOnInit: true }
  );

// Usage:
const myAtom = atomWithMMKV('my-atom-key', 'value');

To migrate existing data from @react-native-async-storage/async-storage to react-native-mmkv, you can implement a migration script that iterates through all keys in AsyncStorage, copies their values to MMKV, and then removes them from AsyncStorage.

Note that AsyncStorage stores everything as strings. When migrating, you should handle boolean conversion (e.g., checking if a string is 'true' or 'false') to ensure data types are preserved correctly in MMKV. It is recommended to use a flag like hasMigratedFromAsyncStorage in MMKV to ensure the migration process only runs once.

import AsyncStorage from '@react-native-async-storage/async-storage';
import { createMMKV } from 'react-native-mmkv';

export const storage = createMMKV();

export const hasMigratedFromAsyncStorage = storage.getBoolean(
  'hasMigratedFromAsyncStorage',
);

export async function migrateFromAsyncStorage(): Promise<void> {
  const keys = await AsyncStorage.getAllKeys();

  for (const key of keys) {
    try {
      const value = await AsyncStorage.getItem(key);

      if (value != null) {
        // Handle boolean conversion from AsyncStorage strings
        if (['true', 'false'].includes(value)) {
          storage.set(key, value === 'true');
        } else {
          storage.set(key, value);
        }

        await AsyncStorage.removeItem(key);
      }
    } catch (error) {
      console.error(`Failed to migrate key "${key}" from AsyncStorage to MMKV!`, error);
      throw error;
    }
  }

  storage.set('hasMigratedFromAsyncStorage', true);
}