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:
- 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.
- 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.
- 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.
| User is asking about… |
Read |
Creating an MMKV instance, configuration options (id, path, encryptionKey, mode, readOnly, compareBeforeSet), the createMMKV() factory |
references/create-instance.md |
Getting/setting values, all data types (string, number, boolean, buffer, objects via JSON), key management (contains, getAllKeys, remove, clearAll), size, trim, importAllFrom |
references/crud-operations.md |
React hooks (useMMKVString, useMMKVNumber, useMMKVBoolean, useMMKVBuffer, useMMKVObject, useMMKV, useMMKVListener, useMMKVKeys), reactive UI |
references/hooks.md |
Listening for value changes outside of React, addOnValueChangedListener, cleaning up listeners |
references/listeners.md |
Encryption (encrypt, decrypt, recrypt), AES-128 vs AES-256, encryptionKey config |
references/encryption.md |
| Migrating from AsyncStorage, data transfer pattern, completion flag |
references/migrate-from-async-storage.md |
zustand persist middleware, redux-persist, jotai atomWithMMKV, react-query persister, MobX |
references/state-management.md |
V4 upgrade, breaking changes from V3, new MMKV() → createMMKV(), .delete() → .remove() |
references/upgrade-v4.md |
| Storage size limits, memory warnings, when to use a database instead |
references/limits-and-gotchas.md |
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-modules
cd ios && pod install
Expo:
npx expo install react-native-mmkv react-native-nitro-modules
npx 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 // string
storage.length // number of keys
storage.byteSize // total file size in bytes
storage.size // (deprecated — use byteSize)
storage.isReadOnly // boolean
storage.isEncrypted // boolean
// Write
storage.set('key', 'string' | 42 | true | arrayBuffer)
// Read
storage.getString('key') // string | undefined
storage.getNumber('key') // number | undefined
storage.getBoolean('key') // boolean | undefined
storage.getBuffer('key') // ArrayBuffer | undefined
// Keys
storage.contains('key') // boolean
storage.getAllKeys() // string[]
storage.remove('key') // boolean (NOTE: was .delete() in V3)
storage.clearAll() // void
// Encryption
storage.encrypt('password')
storage.encrypt('password', 'AES-256')
storage.decrypt()
storage.recrypt('newPassword' | undefined) // (deprecated — use encrypt()/decrypt())
// Maintenance
storage.trim() // free unused space
storage.importAllFrom(otherStorage) // returns count imported
// Listeners
const sub = storage.addOnValueChangedListener((key) => { ... })
sub.remove()
// Static helpers
existsMMKV('my-store') // boolean
deleteMMKV('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
| File |
Description |
| create-instance.md |
createMMKV() factory, all configuration options |
| crud-operations.md |
Set/get all types, key management, objects, buffers |
| hooks.md |
All React hooks for reactive MMKV usage |
| listeners.md |
addOnValueChangedListener, cleanup |
| encryption.md |
Encrypt/decrypt instances, AES options |
| migrate-from-async-storage.md |
Full migration pattern from AsyncStorage |
| state-management.md |
zustand, redux-persist, jotai, react-query, MobX |
| upgrade-v4.md |
V3 → V4 breaking changes and migration |
| limits-and-gotchas.md |
Storage limits, multi-process, logging, common pitfalls |
Problem → Reference Mapping
1---
2name: react-native-mmkv
3description: 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.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/margelo/react-native-mmkv
7 author: margelo
8 scope: react-native-mmkv
9 tags: react-native, mmkv, storage, key-value, encryption, hooks, zustand, redux, jotai, react-query, async-storage, migration, nitro-modules
10---
11
12# react-native-mmkv
13
14A 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.
15
16## Mental model
17
18`react-native-mmkv` is a high-performance, synchronous key-value storage library for React Native, backed by Tencent's [MMKV](https://github.com/Tencent/MMKV) C++ engine via Nitro Modules (JSI). It is ~30x faster than AsyncStorage.
19
20The three things that trip people up:
21
221. **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.
232. **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](https://github.com/margelo/react-native-nitro-sqlite) or WatermelonDB. There is no fixed storage limit — but memory warnings will fire if you go too large.
243. **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](./references/upgrade-v4.md).
25
26> **V4 requires React Native 0.75+.** It works on both the New Architecture and the old architecture (Nitro is backwards compatible).
27
28## Routing table — problem to reference
29
30Load the matching file from `references/` before writing code. Each reference cites real APIs from the library.
31
32| User is asking about… | Read |
33|---|---|
34| Creating an MMKV instance, configuration options (`id`, `path`, `encryptionKey`, `mode`, `readOnly`, `compareBeforeSet`), the `createMMKV()` factory | [`references/create-instance.md`](./references/create-instance.md) |
35| Getting/setting values, all data types (string, number, boolean, buffer, objects via JSON), key management (`contains`, `getAllKeys`, `remove`, `clearAll`), `size`, `trim`, `importAllFrom` | [`references/crud-operations.md`](./references/crud-operations.md) |
36| React hooks (`useMMKVString`, `useMMKVNumber`, `useMMKVBoolean`, `useMMKVBuffer`, `useMMKVObject`, `useMMKV`, `useMMKVListener`, `useMMKVKeys`), reactive UI | [`references/hooks.md`](./references/hooks.md) |
37| Listening for value changes outside of React, `addOnValueChangedListener`, cleaning up listeners | [`references/listeners.md`](./references/listeners.md) |
38| Encryption (`encrypt`, `decrypt`, `recrypt`), AES-128 vs AES-256, `encryptionKey` config | [`references/encryption.md`](./references/encryption.md) |
39| Migrating from AsyncStorage, data transfer pattern, completion flag | [`references/migrate-from-async-storage.md`](./references/migrate-from-async-storage.md) |
40| zustand persist middleware, redux-persist, jotai `atomWithMMKV`, react-query persister, MobX | [`references/state-management.md`](./references/state-management.md) |
41| V4 upgrade, breaking changes from V3, `new MMKV()` → `createMMKV()`, `.delete()` → `.remove()` | [`references/upgrade-v4.md`](./references/upgrade-v4.md) |
42| Storage size limits, memory warnings, when to use a database instead | [`references/limits-and-gotchas.md`](./references/limits-and-gotchas.md) |
43
44If the question doesn't match any row, read [`references/create-instance.md`](./references/create-instance.md) first — most setup questions start there.
45
46## Installation
47
48```bash
49npm install react-native-mmkv react-native-nitro-modules
50cd ios && pod install
51```
52
53Expo:
54```bash
55npx expo install react-native-mmkv react-native-nitro-modules
56npx expo prebuild
57```
58
59After install, rebuild the app. No additional native wiring is required.
60
61## Quick reference — full MMKV instance API
62
63```ts
64import { createMMKV, existsMMKV, deleteMMKV } from 'react-native-mmkv'
65
66const storage = createMMKV({ id: 'my-store' })
67
68// Properties (read-only)
69storage.id // string
70storage.length // number of keys
71storage.byteSize // total file size in bytes
72storage.size // (deprecated — use byteSize)
73storage.isReadOnly // boolean
74storage.isEncrypted // boolean
75
76// Write
77storage.set('key', 'string' | 42 | true | arrayBuffer)
78
79// Read
80storage.getString('key') // string | undefined
81storage.getNumber('key') // number | undefined
82storage.getBoolean('key') // boolean | undefined
83storage.getBuffer('key') // ArrayBuffer | undefined
84
85// Keys
86storage.contains('key') // boolean
87storage.getAllKeys() // string[]
88storage.remove('key') // boolean (NOTE: was .delete() in V3)
89storage.clearAll() // void
90
91// Encryption
92storage.encrypt('password')
93storage.encrypt('password', 'AES-256')
94storage.decrypt()
95storage.recrypt('newPassword' | undefined) // (deprecated — use encrypt()/decrypt())
96
97// Maintenance
98storage.trim() // free unused space
99storage.importAllFrom(otherStorage) // returns count imported
100
101// Listeners
102const sub = storage.addOnValueChangedListener((key) => { ... })
103sub.remove()
104
105// Static helpers
106existsMMKV('my-store') // boolean
107deleteMMKV('my-store') // boolean
108```
109
110## Testing
111
112A mocked MMKV instance is automatically used when testing with Jest or Vitest. Use `createMMKV()` as normal in tests — no manual mocking needed.
113
114## Verifying the skill is loaded
115
116Good test questions:
117
118- *"How do I persist zustand state with MMKV?"* → should produce a `StateStorage` adapter using `storage.set`, `storage.getString`, `storage.remove` — not AsyncStorage wrappers.
119- *"How do I migrate from AsyncStorage to MMKV?"* → should show the batch-copy pattern with a completion flag, not a drop-in replacement.
120- *"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.
121
122## References
123
124| File | Description |
125|------|-------------|
126| [create-instance.md](./references/create-instance.md) | `createMMKV()` factory, all configuration options |
127| [crud-operations.md](./references/crud-operations.md) | Set/get all types, key management, objects, buffers |
128| [hooks.md](./references/hooks.md) | All React hooks for reactive MMKV usage |
129| [listeners.md](./references/listeners.md) | `addOnValueChangedListener`, cleanup |
130| [encryption.md](./references/encryption.md) | Encrypt/decrypt instances, AES options |
131| [migrate-from-async-storage.md](./references/migrate-from-async-storage.md) | Full migration pattern from AsyncStorage |
132| [state-management.md](./references/state-management.md) | zustand, redux-persist, jotai, react-query, MobX |
133| [upgrade-v4.md](./references/upgrade-v4.md) | V3 → V4 breaking changes and migration |
134| [limits-and-gotchas.md](./references/limits-and-gotchas.md) | Storage limits, multi-process, logging, common pitfalls |
135
136## Problem → Reference Mapping
137
138| Problem | Reference | Action |
139|---------|-----------|--------|
140| Don't know where to start | [create-instance.md](./references/create-instance.md) | Create instance with `createMMKV()` |
141| Need reactive UI updates | [hooks.md](./references/hooks.md) | Use `useMMKVString` / `useMMKVObject` etc. |
142| Encrypting sensitive data | [encryption.md](./references/encryption.md) | Call `storage.encrypt(key)` |
143| App uses AsyncStorage, want to switch | [migrate-from-async-storage.md](./references/migrate-from-async-storage.md) | Batch migrate then swap calls |
144| Zustand/Redux/Jotai persistence | [state-management.md](./references/state-management.md) | Wire adapter for your state lib |
145| Upgrading from V3 to V4 | [upgrade-v4.md](./references/upgrade-v4.md) | `new MMKV()` → `createMMKV()`, `.delete()` → `.remove()` |
146| Storage growing too large | [limits-and-gotchas.md](./references/limits-and-gotchas.md) | Trim or move to SQLite |
147| Multi-process data sharing | [limits-and-gotchas.md](./references/limits-and-gotchas.md) | Set `mode: 'multi-process'` |