@minkyumdev/zustand-mmkv-storage

MMKV storage adapter for Zustand persist middleware in React Native.

Features

• Blazing Fast: MMKV is ~30x faster than AsyncStorage
• Lazy Loading: Dynamically imports MMKV only when needed
• Instance Caching: Reuses MMKV instances across calls
• Encryption Support: Built-in encryption for sensitive data
• Direct Access: Access underlying MMKV instance for debugging
• TypeScript Support: Fully typed
• Zero Dependencies: Only peer dependencies (Zustand, react-native-mmkv)

Installation

npm install @minkyumdev/zustand-mmkv-storage

# Peer dependencies
npm install zustand react-native-mmkv

For iOS, run cd ios && pod install after installation.

Usage

Basic (Recommended)

import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import { mmkvStorage } from '@minkyumdev/zustand-mmkv-storage'

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

With Custom ID

Use different IDs to separate storage namespaces:

import { createMMKVStorage } from '@minkyumdev/zustand-mmkv-storage'

// User store
storage: createJSONStorage(() => createMMKVStorage({ id: 'user-storage' }))

// Settings store
storage: createJSONStorage(() => createMMKVStorage({ id: 'settings-storage' }))

With Encryption

For sensitive data like tokens:

storage: createJSONStorage(() => createMMKVStorage({
  id: 'secure-storage',
  encryptionKey: 'your-secret-key',
}))

Hydration Handling

Prevent flash of initial state on app startup:

interface StoreState {
  user: User | null
  hasHydrated: boolean
}

const useStore = create<StoreState>()(
  persist(
    (set) => ({
      user: null,
      hasHydrated: false,
    }),
    {
      name: 'user-store',
      storage: createJSONStorage(() => mmkvStorage),
      onRehydrateStorage: () => (state) => {
        if (state) {
          state.hasHydrated = true
        }
      },
    }
  )
)

// In component
const { user, hasHydrated } = useStore()
if (!hasHydrated) return <Loading />

Direct MMKV Access

Access the underlying MMKV instance for debugging or manual operations:

import { getMMKVInstance } from '@minkyumdev/zustand-mmkv-storage'

const mmkv = getMMKVInstance('user-storage')

// Clear all data
mmkv.clearAll()

// Get all keys
const keys = mmkv.getAllKeys()

API

mmkvStorage

Pre-configured default storage instance. Use this for simple cases.

createMMKVStorage(options?)

Creates a custom storage adapter.

| Option | Type | Default | Description | |--------|------|---------|-------------| | id | string | 'default' | MMKV instance ID | | encryptionKey | string | - | Encryption key for secure storage |

getMMKVInstance(id?, encryptionKey?)

Returns the MMKV instance for direct access. Instances are cached as singletons.

Error Handling

If react-native-mmkv is not installed, a helpful error message with installation instructions will be thrown.

License

MIT