react-native-mmkv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

这是为使用

react-native-mmkv

的项目中的AI代码助手准备的专属参考文档。请通过查阅下方匹配的

references/*.md

文件，使用该库的真实API作答，而非自行编造API。

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+ with New Architecture / TurboModules enabled.

react-native-mmkv

是一款高性能的同步键值存储库，专为React Native打造，通过Nitro Modules（JSI）基于腾讯的MMKV C++引擎开发。它的速度比AsyncStorage快约30倍。

容易让人混淆的三个关键点：

所有操作都是同步的。无需
```
await
```
，也没有Promises。
```
storage.getString('key')
```
会立即返回值。这正是它的核心优势——MMKV通过内存映射文件，在进程内完成读写操作。
它是键值存储，而非数据库。所有数据都缓存到内存中。请将总数据大小控制在约100MB以内；如果是更大的数据集，请使用react-native-nitro-sqlite或WatermelonDB。它没有固定的存储限制，但如果数据过大，会触发内存警告。
V4版本是破坏性重写。构造函数从
```
new MMKV()
```
改为
```
createMMKV()
```
，
```
.delete()
```
方法变为
```
.remove()
```
，且
```
react-native-nitro-modules
```
现在是必填的对等依赖项。请查看升级指南。

V4版本要求React Native 0.75+，且已启用新架构/TurboModules。

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.

在编写代码前，请加载

references/

目录下的匹配文件。每个参考文档都引用了该库的真实API。

用户的问题方向	查阅文档
创建MMKV实例、配置选项（ `id` 、 `path` 、 `encryptionKey` 、 `mode` 、 `readOnly` 、 `compareBeforeSet` ）、 `createMMKV()` 工厂函数	`references/create-instance.md`
获取/设置值、所有数据类型（字符串、数字、布尔值、缓冲区、通过JSON序列化的对象）、键管理（ `contains` 、 `getAllKeys` 、 `remove` 、 `clearAll` ）、 `size` 、 `trim` 、 `importAllFrom`	`references/crud-operations.md`
React hooks（ `useMMKVString` 、 `useMMKVNumber` 、 `useMMKVBoolean` 、 `useMMKVBuffer` 、 `useMMKVObject` 、 `useMMKV` 、 `useMMKVListener` 、 `useMMKVKeys` ）、响应式UI	`references/hooks.md`
在React外部监听值变更、 `addOnValueChangedListener` 、监听器清理	`references/listeners.md`
加密（ `encrypt` 、 `decrypt` 、 `recrypt` ）、AES-128与AES-256对比、 `encryptionKey` 配置	`references/encryption.md`
从AsyncStorage迁移、数据传输模式、完成标记	`references/migrate-from-async-storage.md`
zustand持久化中间件、redux-persist、jotai `atomWithMMKV` 、react-query持久化器、MobX	`references/state-management.md`
V4版本升级、V3到V4的破坏性变更、 `new MMKV()` → `createMMKV()` 、 `.delete()` → `.remove()`	`references/upgrade-v4.md`
存储大小限制、内存警告、何时改用数据库	`references/limits-and-gotchas.md`

如果问题与任何一行都不匹配，请先查阅

references/create-instance.md

——大多数配置类问题都从这里开始。

Installation

安装

bash

npm install react-native-mmkv react-native-nitro-modules
cd ios && pod install

Expo:

bash

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

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

bash

npm install react-native-mmkv react-native-nitro-modules
cd ios && pod install

Expo环境：

bash

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

安装完成后，重新构建应用。无需额外的原生配置。

Quick reference — full MMKV instance API

快速参考——完整MMKV实例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.size        // total file size in bytes
storage.byteSize    // byte size
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)

// 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

import { createMMKV, existsMMKV, deleteMMKV } from 'react-native-mmkv'

const storage = createMMKV({ id: 'my-store' })

// 只读属性
storage.id          // string类型
storage.length      // 键的数量
storage.size        // 文件总大小（字节）
storage.byteSize    // 字节大小
storage.isReadOnly  // 布尔值
storage.isEncrypted // 布尔值

// 写入操作
storage.set('key', 'string' | 42 | true | arrayBuffer)

// 读取操作
storage.getString('key')   // string | undefined
storage.getNumber('key')   // number | undefined
storage.getBoolean('key')  // boolean | undefined
storage.getBuffer('key')   // ArrayBuffer | undefined

// 键管理
storage.contains('key')    // 布尔值
storage.getAllKeys()        // string[]类型
storage.remove('key')      // 布尔值 （注意：V3版本中是.delete()）
storage.clearAll()         // 无返回值

// 加密操作
storage.encrypt('password')
storage.encrypt('password', 'AES-256')
storage.decrypt()
storage.recrypt('newPassword' | undefined)

// 维护操作
storage.trim()                       // 释放未使用空间
storage.importAllFrom(otherStorage)  // 返回导入的数量

// 监听器
const sub = storage.addOnValueChangedListener((key) => { ... })
sub.remove()

// 静态辅助方法
existsMMKV('my-store')   // 布尔值
deleteMMKV('my-store')   // 布尔值

Testing

测试

A mocked MMKV instance is automatically used when testing with Jest or Vitest. Use

createMMKV()

as normal in tests — no manual mocking needed.

使用Jest或Vitest进行测试时，会自动使用模拟的MMKV实例。测试中正常使用

createMMKV()

即可——无需手动模拟。

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.

测试示例问题：

"如何使用MMKV持久化zustand状态？" → 应生成使用
```
storage.set
```
、
```
storage.getString
```
、
```
storage.remove
```
的
```
StateStorage
```
适配器，而非AsyncStorage包装器。
"如何从AsyncStorage迁移到MMKV？" → 应展示带完成标记的批量复制模式，而非直接替换。
"存储限制是多少？" → 应说明没有固定限制，但数据是内存映射的，所以建议控制在约100MB以内；更大的数据集请使用SQLite。

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

文件	描述
create-instance.md	`createMMKV()` 工厂函数及所有配置选项
crud-operations.md	所有类型的增删改查操作、键管理、对象与缓冲区处理
hooks.md	所有用于响应式MMKV操作的React hooks
listeners.md	`addOnValueChangedListener` 及监听器清理
encryption.md	实例加密/解密、AES选项
migrate-from-async-storage.md	从AsyncStorage迁移的完整模式
state-management.md	zustand、redux-persist、jotai、react-query、MobX集成
upgrade-v4.md	V3到V4的破坏性变更及迁移指南
limits-and-gotchas.md	存储限制、多进程、日志、常见陷阱

Problem → Reference Mapping

问题→参考文档映射

Problem	Reference	Action
Don't know where to start	create-instance.md	Create instance with `createMMKV()`
Need reactive UI updates	hooks.md	Use `useMMKVString` / `useMMKVObject` etc.
Encrypting sensitive data	encryption.md	Call `storage.encrypt(key)`
App uses AsyncStorage, want to switch	migrate-from-async-storage.md	Batch migrate then swap calls
Zustand/Redux/Jotai persistence	state-management.md	Wire adapter for your state lib
Upgrading from V3 to V4	upgrade-v4.md	`new MMKV()` → `createMMKV()` , `.delete()` → `.remove()`
Storage growing too large	limits-and-gotchas.md	Trim or move to SQLite
Multi-process data sharing	limits-and-gotchas.md	Set `mode: 'multi-process'`

问题	参考文档	操作建议
不知道从何入手	create-instance.md	使用 `createMMKV()` 创建实例
需要响应式UI更新	hooks.md	使用 `useMMKVString` / `useMMKVObject` 等hooks
加密敏感数据	encryption.md	调用 `storage.encrypt(key)`
应用使用AsyncStorage，想要切换到MMKV	migrate-from-async-storage.md	批量迁移后替换调用代码
Zustand/Redux/Jotai状态持久化	state-management.md	为你的状态库适配对应的适配器
从V3升级到V4	upgrade-v4.md	将 `new MMKV()` 改为 `createMMKV()` ， `.delete()` 改为 `.remove()`
存储数据过大	limits-and-gotchas.md	清理空间或改用SQLite
多进程数据共享	limits-and-gotchas.md	设置 `mode: 'multi-process'`