React Native MMKV — Ultra-Fast Key-Value Storage for Mobile

Introduction

React Native MMKV wraps the MMKV storage engine originally developed by WeChat for its billion-user mobile app. It provides synchronous read and write operations that are dramatically faster than AsyncStorage, making it ideal for apps that frequently access persisted state.

What React Native MMKV Does

• Stores strings, numbers, booleans, and byte arrays with synchronous get/set methods
• Provides AES-256 encryption for sensitive data with a single constructor option
• Supports multiple named storage instances for logical data separation
• Offers hooks for React components to re-render when stored values change
• Runs on iOS, Android, and web with a consistent API

Architecture Overview

MMKV uses memory-mapped files (mmap) to persist data, which means writes go to a shared memory region and are flushed to disk asynchronously by the OS. The library accesses native code via JSI (JavaScript Interface) rather than the bridge, enabling synchronous calls without the overhead of JSON serialization. This architecture is what makes it roughly 30 times faster than AsyncStorage for typical operations.

Self-Hosting & Configuration

• Install via npm and run pod-install for iOS native linking
• Create instances with new MMKV() for the default store or new MMKV({ id: 'myStore' }) for named stores
• Enable encryption by passing encryptionKey in the constructor options
• Use the useMMKVString, useMMKVNumber, and useMMKVBoolean hooks for reactive state in components
• Configure the storage directory path for custom file locations on both platforms

Key Features

• Synchronous API that does not require await or callbacks for reads and writes
• JSI-based native bridge for minimal overhead and direct memory access
• AES-256 encryption with a single constructor flag for secure storage
• React hooks that trigger re-renders when stored values change
• Multi-process access support for apps with background services or extensions

Comparison with Similar Tools

• AsyncStorage — the default RN storage; MMKV is roughly 30x faster with a synchronous API
• WatermelonDB — a full relational database for large datasets; MMKV is a simple key-value store
• Realm — object database with sync features; MMKV is lighter for flat key-value needs
• MMKV (native) — the underlying C++ library by Tencent; this package adds React Native bindings
• SecureStore (Expo) — uses Keychain/Keystore for secrets; MMKV offers encryption with higher throughput

FAQ

Q: Is MMKV safe for storing authentication tokens? A: With encryption enabled, MMKV stores data encrypted at rest. For the highest security, combine it with platform keychains for the encryption key itself.

Q: Can I migrate from AsyncStorage? A: Yes. Read all keys from AsyncStorage, write them to MMKV, then remove the AsyncStorage data. The API surface is similar enough for a straightforward migration.

Q: Does it work with Expo? A: It works with Expo bare workflow and custom dev clients. It is not compatible with Expo Go since it requires native modules.

Q: What happens if the app crashes during a write? A: MMKV uses CRC checksums and mmap-based writes. Partial writes are detected and recovered automatically on the next launch.

Sources

• https://github.com/mrousavy/react-native-mmkv
• https://mrousavy.com/react-native-mmkv/