Skip to content

huytdps13400/react-native-ssl-manager / .agents/skills/react-native-mmkv

react-native-mmkv

Verified

Fast synchronous key-value storage for React Native via react-native-mmkv (Nitro-backed). Covers creating and configuring MMKV instances, reading/writing all value types (string, number, boolean, buffer), React hooks for reactive UI, value-change listeners, encryption, AsyncStorage migration, and state-management integrations (zustand, redux-persist, jotai, react-query). Also covers storage limits, multi-process mode, and the V4 upgrade from the class-based API.

references/state-management.md

View on GitHub
---
id: state-management
title: State management integrations
scope: react-native-mmkv
keywords: zustand, redux, redux-persist, jotai, react-query, tanstack, mobx, persist, middleware, adapter, wrapper, atomWithMMKV, StateStorage
---

# State management integrations

## Mental model

MMKV is synchronous, but most state-management persistence layers expect an async storage interface. The wrappers below bridge that gap — they're thin adapters that map each library's storage contract to MMKV's `set`/`getString`/`remove`.

## Zustand persist middleware

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

const storage = createMMKV()

export 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)
  },
}
```

Usage in a zustand store:

```ts
import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import { zustandStorage } from './storage'

const useStore = create(
  persist(
    (set) => ({
      count: 0,
      increment: () => set((s) => ({ count: s.count + 1 })),
    }),
    {
      name: 'my-store',
      storage: createJSONStorage(() => zustandStorage),
    },
  ),
)
```

## Redux persist

```ts
import { Storage } from 'redux-persist'
import { createMMKV } from 'react-native-mmkv'

const storage = createMMKV()

export const reduxStorage: Storage = {
  setItem: (key, value) => {
    storage.set(key, value)
    return Promise.resolve(true)
  },
  getItem: (key) => {
    const value = storage.getString(key)
    return Promise.resolve(value)
  },
  removeItem: (key) => {
    storage.remove(key)
    return Promise.resolve()
  },
}
```

Usage:

```ts
import { persistStore, persistReducer } from 'redux-persist'
import { reduxStorage } from './storage'

const persistConfig = {
  key: 'root',
  storage: reduxStorage,
}
```

## Jotai — `atomWithMMKV`

```ts
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:

```ts
const myAtom = atomWithMMKV('my-atom-key', 'default-value')
```

`createJSONStorage` handles `JSON.stringify`/`JSON.parse` automatically. See [Jotai docs](https://jotai.org/docs/utils/atom-with-storage).

## React Query (TanStack Query)

1. Install persist packages:

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

2. Create the persister:

```ts
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
import { createMMKV } from 'react-native-mmkv'

const storage = createMMKV()

const clientStorage = {
  setItem: (key: string, value: string) => {
    storage.set(key, value)
  },
  getItem: (key: string) => {
    const value = storage.getString(key)
    return value === undefined ? null : value
  },
  removeItem: (key: string) => {
    storage.remove(key)
  },
}

export const clientPersister = createAsyncStoragePersister({
  storage: clientStorage,
})
```

3. Wire it in your root component:

```tsx
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { clientPersister } from './storage'

const App = () => {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{ persister: clientPersister }}
    >
      {/* your app */}
    </PersistQueryClientProvider>
  )
}
```

## Gotchas

- **All adapters are thin wrappers.** The actual persistence is synchronous — the `Promise.resolve()` wrappers in redux-persist are just satisfying the interface contract.
- **JSON serialization is handled by the state library.** Zustand's `createJSONStorage`, jotai's `createJSONStorage`, and redux-persist all stringify before calling `setItem`. Don't double-stringify.
- **Jotai's `subscribe` is the differentiator.** The jotai adapter is the only one that wires up `addOnValueChangedListener` for live reactivity. The others rely on the state library's own change tracking.
- **One MMKV instance can back multiple stores.** All adapters can share the same `createMMKV()` instance. Keys won't collide as long as each store uses a unique `name`/`key` prefix.

## Pointers

- Official zustand wrapper: [WRAPPER_ZUSTAND_PERSIST_MIDDLEWARE.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_ZUSTAND_PERSIST_MIDDLEWARE.md)
- Official redux wrapper: [WRAPPER_REDUX.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_REDUX.md)
- Official jotai wrapper: [WRAPPER_JOTAI.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_JOTAI.md)
- Official react-query wrapper: [WRAPPER_REACT_QUERY.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_REACT_QUERY.md)
- Official MobX wrapper: [WRAPPER_MOBX.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_MOBX.md)
- Official Recoil wrapper: [WRAPPER_RECOIL.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_RECOIL.md)
- Official TinyBase wrapper: [WRAPPER_TINYBASE.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/WRAPPER_TINYBASE.md)
- Related: [create-instance.md](./create-instance.md), [listeners.md](./listeners.md)
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall