react-native-mmkv: Fast Key-Value Storage for React Native

Synchronous key-value storage replacing the async bridge

react-native-mmkv wraps MMKV, a key-value storage framework developed by WeChat that uses a memory-mapped file approach for efficient reads and writes. Instead of using React Native's async Bridge (which serializes calls and queues them), react-native-mmkv provides direct JavaScript bindings through JSI (JavaScript Interface) to the native C++ library. This makes every call synchronous: when you call storage.getString('key'), you get the result immediately without waiting for a bridge callback.

Benchmarks in the README measure reading a single value 1000 times on an iPhone 11 Pro: AsyncStorage takes roughly 1000ms, while MMKV completes in about 30ms. For apps that check user settings, cache calculations, or store temporary state frequently, this difference accumulates. If your app calls storage 100 times per session, you save about 3 seconds of UI wait time just on storage access. The 30x speedup comes from eliminating the serialization and queue overhead of the Bridge layer and using memory-mapped file I/O, which is optimized for repeated small reads.

Version 4, released in March 2026, is a Nitro module, which means it uses C++ Nitro bindings instead of the deprecated Bridge. Version 3 and earlier relied on the older async Bridge architecture. The V4 upgrade guide in the repository documents the migration path and the performance implications of moving to direct native bindings. The monorepo structure (packages/react-native-mmkv for the library, example for the test app) lets contributors develop and test changes rapidly.

Installation and initialization patterns

Installation depends on your build setup. For a standard React Native project:

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

For Expo projects, which have limited support for native modules:

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

The react-native-nitro-modules dependency is required for Nitro module support; Expo will prebuild the native code into a development client. The GitHub repository includes an example app demonstrating setup and usage.

The README recommends exporting a single shared instance throughout your app instead of creating a new storage object each time. A typical pattern is creating a file that exports the initialized storage:

import { createMMKV } from 'react-native-mmkv'

export const storage = createMMKV()

Then import that instance in your components and call synchronous methods directly. You can also use React Hooks: `useMMKVString`, `useMMKVNumber`, and `useMMKVBoolean` return a value and a setter function that trigger component re-renders when the stored value changes. This pattern avoids Redux boilerplate for simple state that needs persistence. The package is built with TypeScript and includes type definitions for all methods.

Configuration, encryption, and multi-process mode

When creating an instance with `createMMKV`, you pass a configuration object. The most important options are:

`id` sets the storage namespace. If you want to use multiple instances, assign different IDs. A common pattern is creating a global storage instance with the default ID (`mmkv.default`) and a per-user instance with ID `user-${userId}-storage`.

`path` customizes the root directory where files are stored. By default, MMKV stores data in `$(Documents)/mmkv/`. If you need to customize this directory on iOS or Android, pass an absolute path.

`encryptionKey` and `encryptionType` enable encryption. By default, MMKV stores values as plain text on disk, relying on iOS and Android sandboxing to prevent access. If you need application-level encryption (for sensitive tokens or personal data), pass an `encryptionKey` string and set `encryptionType` to either `AES-128` (the default when encryption is enabled) or `AES-256`.

`mode` can be set to `multi-process` to allow other apps or app extensions in the same app group to read and write to the same storage. This is necessary if you use app clips, watchOS extensions, or shared container functionality. When `multi-process` is enabled, MMKV uses file locking to coordinate access.

`readOnly` makes the instance read-only, which the README notes is more efficient if you only need to read values. Any call to `set()` on a read-only instance will throw.

`compareBeforeSet` makes MMKV compare values for equality before writing. This can improve performance if the same values are written repeatedly.

Data types, serialization, and design constraints

react-native-mmkv supports four atomic types: strings, numbers, booleans, and ArrayBuffers. For complex objects, you serialize to JSON before storing. The README shows examples with a user object containing a username and age: you convert it to a JSON string, store it, and parse it back when retrieving.

Methods for retrieval are type-specific: `getString`, `getNumber`, `getBoolean`, and `getArrayBuffer`. If you call `getString` on a key that does not exist, it returns `undefined`. You can check for key existence with `contains(key)`, get all keys with `getAllKeys()`, delete a key with `remove(key)`, and clear all data with `clearAll()`.

The README does not document maximum value sizes or performance characteristics for large values. If you store large objects (multi-megabyte blobs), measure first. MMKV is designed for small to medium key-value data typical of app preferences and state, not for storing high-resolution images or video files.

One design implication: because MMKV is synchronous and stores data in a memory-mapped file, large reads can briefly block the JavaScript thread. For app-critical performance, keep values small and access them infrequently from hot code paths like render methods.

Multiple instances for user isolation and shared data

A key pattern in MMKV is creating separate instances for global and user-specific data. When a user logs in, you initialize a user-specific instance with `createMMKV({ id: `user-${userId}-storage` })`. When the user logs out, you can call `storage.clearAll()` on the user instance without affecting app-level settings stored in the global instance.

Each instance has its own encryption settings, storage path, and read-only state. This separation allows your app to persist global preferences (theme, language, feature flags) while securely isolating per-user data (authentication tokens, cached user profile). Different instances can use different IDs, encryption keys, and storage paths, so you can encrypt sensitive user data with a unique key while leaving public app state unencrypted.

The README mentions that if you use app groups on iOS, you open `Info.plist` and create an `AppGroupIdentifier` key with your app group's value. MMKV automatically detects this and stores data in the app group container, readable by other apps and extensions in the same group. This is useful for storing data shared between a main app and a watch extension, or for app clips that need to access app data. This requires enabling `mode: 'multi-process'` to coordinate access with file locking.

Maintenance status and ecosystem integration

The latest release is v4.3.2 (2026-06-22). Preceding releases include v4.3.1 (2026-04-07) and v4.3.0 (2026-03-20). The last push to the repository was on 2026-09-14. The license is MIT. The package is published to npm as `react-native-mmkv` and maintained by Marc Rousavy, who also authored the StorageBenchmark project that benchmarks react-native-mmkv against other storage libraries.

react-native-mmkv integrates with state management libraries. Users on GitHub compare it to Zustand and Redux, and the README mentions it is useful for persisting Zustand state. For apps without a state manager, the Hooks API is sufficient. The repository includes a V3 documentation file (README_V3.md) for teams still on the older async bridge architecture, and a V4 upgrade guide for teams migrating to Nitro modules. Supporting both versions helps developers transition at their own pace.

Editorial conclusion

react-native-mmkv is for React Native teams needing fast, synchronous key-value storage for user preferences, app state, or caching. Use it if your app accesses storage frequently, expects synchronous reads and writes, or if you need storage encryption. Skip it if you need relational queries, complex transactions, or if your build system cannot accommodate Nitro modules. Verify first that the Nitro module approach works with your build setup, test multi-process mode if you use app extensions, and benchmark storage access in your specific scenario to ensure you gain the expected performance improvement.

Frequently asked questions

Official sources

1. License: MIT
2. margelo/react-native-mmkv on GitHub
3. Project website
4. README
5. Releases