react-native-mmkv

react-native-mmkv

react-native-mmkv を使用するプロジェクトで作業する AI コーディングアシスタント向けの、要点を絞ったリファレンスです。以下の該当する references/*.md ファイルを参照し、このライブラリの実際の API を使って回答してください。存在しない API を作り出さないでください。

基本的な考え方

react-native-mmkv は、Nitro Modules（JSI）を介して Tencent の MMKV C++ エンジンを使用する、高性能で同期的な React Native 向けキーバリューストレージライブラリです。AsyncStorage より約 30 倍高速です。

つまずきやすいポイントは 3 つです。

1. すべて同期処理です。 await も Promise もありません。storage.getString('key') は値をすぐに返します。これこそがこのライブラリの要点です。MMKV はファイルをメモリマップし、プロセス内で読み書きします。
2. データベースではなく、キーバリューストアです。 すべてのデータはメモリにキャッシュされます。合計サイズは約 100 MB 未満に抑えてください。より大きなデータセットには、react-native-nitro-sqlite または WatermelonDB を使用してください。固定のストレージ上限はありませんが、サイズが大きくなりすぎるとメモリ警告が発生します。
3. V4 は破壊的変更を伴う全面的な書き直しです。 コンストラクターが new MMKV() から createMMKV() に変わり、.delete() は .remove() になりました。また、react-native-nitro-modules が必須のピア依存関係になりました。アップグレードガイドを参照してください。

V4 には React Native 0.75 以降が必要です。 新アーキテクチャと旧アーキテクチャの両方で動作します（Nitro は後方互換性があります）。

ルーティング表 — 問題からリファレンスへ

コードを書く前に、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 フック（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 の persist ミドルウェア、redux-persist、jotai の atomWithMMKV、react-query の persister、MobX	references/state-management.md
V4 へのアップグレード、V3 からの破壊的変更、new MMKV() → createMMKV()、.delete() → .remove()	references/upgrade-v4.md
ストレージサイズの上限、メモリ警告、データベースを使用すべき場合	references/limits-and-gotchas.md

質問がどの行にも当てはまらない場合は、まず references/create-instance.md を読んでください。セットアップに関する質問の多くは、ここから始めます。

インストール

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

インストール後、アプリを再ビルドしてください。追加のネイティブ設定は不要です。

クイックリファレンス — 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.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

テスト

Jest または Vitest でテストする場合、モックされた MMKV インスタンスが自動的に使用されます。テストでは通常どおり createMMKV() を使用してください。手動でのモックは不要です。

スキルが読み込まれていることを確認する

テストに適した質問：

• 「zustand の状態を MMKV で永続化するにはどうすればよいですか？」 → storage.set、storage.getString、storage.remove を使用する StateStorage アダプターを提示するはずです。AsyncStorage のラッパーではありません。
• 「AsyncStorage から MMKV に移行するにはどうすればよいですか？」 → そのまま置き換える方法ではなく、完了フラグを使った一括コピーのパターンを示すはずです。
• 「ストレージの上限はどのくらいですか？」 → 固定の上限はありませんが、データはメモリマッピングされるため、約 100 MB 未満に保ち、大きなデータセットには SQLite を使うよう説明するはずです。

参考資料

ファイル	説明
create-instance.md	createMMKV() ファクトリーとすべての設定オプション
crud-operations.md	すべての型の設定と取得、キーの管理、オブジェクト、バッファー
hooks.md	リアクティブな MMKV の使用に対応するすべての React フック
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	ストレージの上限、マルチプロセス、ログ出力、よくある落とし穴

問題 → 参考資料の対応表

問題	参考資料	対応
何から始めればよいかわからない	create-instance.md	createMMKV() でインスタンスを作成する
リアクティブな UI 更新が必要	hooks.md	useMMKVString／useMMKVObject などを使用する
機密データを暗号化したい	encryption.md	storage.encrypt(key) を呼び出す
アプリで AsyncStorage を使用しており、切り替えたい	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' を設定する