React Native Mmkv

react-native-mmkv

A focused reference for AI coding assistants working in a project that uses react-native-mmkv. Answer using the real APIs from this library — not invented ones — by routing to the matching references/*.md file below.

Mental model

react-native-mmkv is a high-performance, synchronous key-value storage library for React Native, backed by Tencent's MMKV C++ engine via Nitro Modules (JSI). It is ~30x faster than AsyncStorage.

The three things that trip people up:

1. Everything is synchronous. No await, no Promises. storage.getString('key') returns the value immediately. This is the whole point — MMKV memory-maps files and reads/writes in-process.
2. It's a key-value store, not a database. All data is cached in memory. Keep total size under ~100 MB; for larger datasets use react-native-nitro-sqlite or WatermelonDB. There is no fixed storage limit — but memory warnings will fire if you go too large.
3. V4 is a breaking rewrite. The constructor changed from new MMKV() to createMMKV(), .delete() became .remove(), and react-native-nitro-modules is now a required peer dependency. See the upgrade guide.

V4 requires React Native 0.75+. It works on both the New Architecture and the old architecture (Nitro is backwards compatible).

Routing table — problem to reference

Load the matching file from references/ before writing code. Each reference cites real APIs from the library.

If the question doesn't match any row, read references/create-instance.md first — most setup questions start there.

Installation

npm install react-native-mmkv react-native-nitro-modulescd ios && pod install

Expo:

npx expo install react-native-mmkv react-native-nitro-modulesnpx expo prebuild

After install, rebuild the app. No additional native wiring is required.

Quick reference — full MMKV instance API

import { createMMKV, existsMMKV, deleteMMKV } from 'react-native-mmkv'
const storage = createMMKV({ id: 'my-store' })
// Properties (read-only)storage.id          // stringstorage.length      // number of keysstorage.byteSize    // total file size in bytesstorage.size        // (deprecated — use byteSize)storage.isReadOnly  // booleanstorage.isEncrypted // boolean
// Writestorage.set('key', 'string' | 42 | true | arrayBuffer)
// Readstorage.getString('key')   // string | undefinedstorage.getNumber('key')   // number | undefinedstorage.getBoolean('key')  // boolean | undefinedstorage.getBuffer('key')   // ArrayBuffer | undefined
// Keysstorage.contains('key')    // booleanstorage.getAllKeys()        // string[]storage.remove('key')      // boolean  (NOTE: was .delete() in V3)storage.clearAll()         // void
// Encryptionstorage.encrypt('password')storage.encrypt('password', 'AES-256')storage.decrypt()storage.recrypt('newPassword' | undefined)  // (deprecated — use encrypt()/decrypt())
// Maintenancestorage.trim()                       // free unused spacestorage.importAllFrom(otherStorage)  // returns count imported
// Listenersconst sub = storage.addOnValueChangedListener((key) => { ... })sub.remove()
// Static helpersexistsMMKV('my-store')   // booleandeleteMMKV('my-store')   // boolean

Testing

A mocked MMKV instance is automatically used when testing with Jest or Vitest. Use createMMKV() as normal in tests — no manual mocking needed.

Verifying the skill is loaded

Good test questions:

• "How do I persist zustand state with MMKV?" → should produce a StateStorage adapter using storage.set, storage.getString, storage.remove — not AsyncStorage wrappers.
• "How do I migrate from AsyncStorage to MMKV?" → should show the batch-copy pattern with a completion flag, not a drop-in replacement.
• "What's the storage limit?" → should explain there's no fixed limit, but data is memory-mapped so keep it under ~100 MB; use SQLite for larger datasets.

References

Problem → Reference Mapping