react-native-mmkv: MMKV key/value storage in React Native, and when it is the wrong tool
⚡️ The fastest key/value storage for React Native. ~30x faster than AsyncStorage!
At a glance
- What is it?
- react-native-mmkv binds Tencent's MMKV C++ key/value store directly to JavaScript through JSI and Nitro Modules, giving synchronous reads and writes. It suits small app state and settings, not large relational data.
- Who is it for?
- Adopt react-native-mmkv if you need synchronous key/value access for settings, session flags or small cached payloads, and you are on React Native with Nitro Modules available. Do not adopt it as a replacement for a relational database, and do not expect the Expo Go client to run it, since the README's Expo path goes through npx expo prebuild.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- margelo/react-native-mmkv8,530 ★ · +23
| Repository | 2026-09-22 | 2026-11-21 |
|---|---|---|
| margelo/react-native-mmkv | 8.5k | 8.5k |
23 Stars in the last 60 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What react-native-mmkv solves, and who it is for
Mobile apps constantly read and write small pieces of state: a session token, a theme choice, the last tab the user opened, a cached API response. The default answer in React Native has been AsyncStorage, whose API is asynchronous, so every read returns a Promise and every write has to be awaited. That shape pushes state loading into effects and forces you to handle the window where the value is not there yet.
react-native-mmkv takes a different route. It is a React Native library that exposes Tencent's MMKV, described in the README as "an efficient, small mobile key-value storage framework developed by WeChat", through direct JS bindings to the native C++ library. The README lists the feature set plainly: get and set for strings, booleans, numbers and ArrayBuffers; fully synchronous calls with no async/await, no Promises and no Bridge; encryption support; multiple instances; a customizable storage location; and iOS, Android and Web support.
The intended audience is React Native developers storing small to medium key/value data who care about read latency on the JS thread. The README's headline claim is that it is "~30x faster than AsyncStorage", and it points to a separate StorageBenchmark repository that measures reading a value 1000 times on an iPhone 11 Pro. That number comes from the project's own benchmark, not from independent measurement, and it measures one operation shape rather than your app's access pattern.
How the JSI and Nitro Modules binding actually works
The mechanism is the interesting part. Older React Native native modules cross the Bridge, which serializes data between the JS and native worlds and makes calls asynchronous by construction. react-native-mmkv skips that: the README states it uses JSI and C++ NitroModules instead of the old Bridge. JSI lets JavaScript call into C++ functions directly, which is why the API can be synchronous and why a getString call returns a value rather than a Promise.
In V4 the library is a Nitro Module. That is a structural change, not a cosmetic one: the upgrade path from V3 is documented separately, and the README links a V4 upgrade guide for anyone moving across. If you are on V3, the V4 README is not the document you want; the repository keeps a README_V3.md for that case.
Data flow is straightforward. You create a storage instance, which maps to an MMKV instance identified by an id. Values are written into that instance and persisted to a file. By default, the README says, MMKV stores files inside $(Documents)/mmkv/, and the whole file is plain text unless you supply an encryption key. That last detail matters more than the performance claims for anyone storing credentials. The README is explicit that MMKV "stores all key-values in plain text on file, relying on iOS's/Android's sandbox to make sure the file is encrypted", and that you can choose to encrypt MMKV if you worry about information leaking. Sandboxing is a boundary, not a cryptographic guarantee, and it stops protecting you the moment a device is jailbroken or a backup is extracted.
Installing react-native-mmkv and creating your first instance
The README gives two install paths. For a bare React Native project, install the library together with react-native-nitro-modules, then run pod install for iOS. The second package is not optional: V4 depends on Nitro Modules at runtime.
npm install react-native-mmkv react-native-nitro-modules
cd ios && pod installFor an Expo project the README uses the Expo installer and then a prebuild step.
npx expo install react-native-mmkv react-native-nitro-modules
npx expo prebuildThat prebuild line is the practical answer to whether this works in Expo Go. It does not: prebuild generates the native projects, which is what a library with a C++ native module needs. If you are staying inside the managed Expo Go client, this library is not available to you.
Once installed, create an instance and export it. The README recommends reusing one instance throughout the app rather than constructing a new one each time.
import { createMMKV } from 'react-native-mmkv'
export const storage = createMMKV()This uses the default storage ID, which the README names as mmkv.default. From there, reads and writes are plain synchronous calls, and the README shows the expected return values in comments.
storage.set('user.name', 'Marc')
storage.set('user.age', 21)
const username = storage.getString('user.name') // 'Marc'
const age = storage.getNumber('user.age') // 21For React components the library also ships hooks, so a value can be read and written without manual subscription code.
const [username, setUsername] = useMMKVString('user.name')
const [age, setAge] = useMMKVNumber('user.age')The first real decision you make is the instance id. A single default instance is fine for app-wide settings. Separate ids are the documented way to keep a logged-in user's data apart from global data.
Configuring instances, encryption and multi-process access
The constructor accepts an options object, and each field changes behaviour in a way worth understanding before you ship. The README's full example looks like this.
import { createMMKV } from 'react-native-mmkv'
export const storage = createMMKV({
id: `user-${userId}-storage`,
path: `${USER_DIRECTORY}/storage`,
encryptionKey: 'hunter2',
encryptionType: 'AES-256',
mode: 'multi-process',
readOnly: false,
compareBeforeSet: false,
})Several of these have consequences the README spells out. The id is required if path or encryptionKey is specified. encryptionKey turns on encryption, and encryptionType defaults to AES-128 with AES-256 available. mode set to multi-process tells MMKV that data can be changed from outside the process, which is the setting for App Clips, Extensions or App Groups. readOnly is described as typically more efficient and as a guard against unwanted writes, and any call to set(..) will throw. compareBeforeSet compares values for equality before writing, and the README notes it is disabled by default and may improve performance when the same values are written repeatedly.
My read on this API surface is that it is honest about trade-offs rather than hiding them. readOnly throwing on set is a deliberate failure rather than a silent no-op, which is the right call for a storage layer. compareBeforeSet being off by default is also defensible, since a comparison has its own cost, but it means the library will happily rewrite identical values unless you opt in.
On iOS, sharing data with extensions or other apps in the same group goes through an AppGroupIdentifier key in Info.plist, after which the README says MMKV stores data inside the app group automatically. That is an Apple platform mechanism, not something the library abstracts away.
Where react-native-mmkv is the wrong choice
The clearest limitation is shape, not speed. MMKV is a key/value store. There is no query language, no indexes, no joins and no partial reads across a dataset. If your data has relationships, or you need to ask questions like "all orders placed last week", a key/value store forces you to load and filter in JavaScript, and the synchronous API that makes reads fast also means that filtering work happens on the JS thread. The comparison with SQLite sits at exactly this boundary, and the honest answer is that they solve different problems rather than one replacing the other.
Storage size is the second boundary. The README describes a file-based store with a default location under $(Documents)/mmkv/. Treating it as a blob store for large media or long lists is a design decision the documentation does not endorse.
The third issue is encryption defaults. Without encryptionKey, values are plain text on disk, protected by the platform sandbox. That is a reasonable default for a theme preference and a poor one for a refresh token. The README is clear about this, but it is easy to skim past, and the mistake is invisible at runtime because everything still works.
Finally, V4 is a Nitro Module, and the README directs V3 users to a separate upgrade guide. That is a migration cost you inherit if you are already on V3, and a compatibility question you have to answer before starting on V4.
Alternatives and how their approach differs
AsyncStorage is the direct comparison, and the difference is architectural. AsyncStorage crosses the React Native Bridge and is asynchronous, so reads return Promises. react-native-mmkv uses JSI and C++ NitroModules, so reads are synchronous and return values. That is why the same code path can be simpler: no loading state for a value you need during the first render. The README's benchmark claim of roughly 30x comes from reading a value 1000 times on an iPhone 11 Pro, measured by the project's own StorageBenchmark repository. If your workload is a handful of writes per session, the latency difference will not be what you notice; the synchronous API will be.
SQLite, typically through a React Native binding, is the other alternative, and it is not a drop-in swap. SQLite gives you tables, indexes and SQL queries, and pays for that with a schema, migrations and asynchronous access in most bindings. Choose SQLite when the data has structure and you need to query it. Choose MMKV when the data is a set of independent values you look up by key.
Zustand is a different kind of comparison, and the comparison react-native-mmkv vs zustand mixes categories. Zustand is an in-memory state manager for React; it does not persist anything by itself. The common pattern is to combine them, using Zustand for in-memory state and MMKV as the persistence layer behind it. That is composition, not competition, and reading the comparison as a choice between two storage engines will lead you the wrong way.
Editorial conclusion
Adopt react-native-mmkv if you need synchronous key/value access for settings, session flags or small cached payloads, and you are on React Native with Nitro Modules available. Do not adopt it as a replacement for a relational database, and do not expect the Expo Go client to run it, since the README's Expo path goes through npx expo prebuild. Before committing, verify your React Native version against the V4 upgrade guide, confirm that react-native-nitro-modules installs cleanly on both platforms, and decide up front whether you need encryptionKey.
Frequently asked questions
What is react-native-mmkv?
It is a React Native library that exposes Tencent's MMKV key/value storage framework through direct JS bindings to the native C++ library. The README describes it as the fastest key/value storage for React Native, with fully synchronous calls and no Bridge.
What is MMKV used for?
MMKV itself is a mobile key/value storage framework developed by WeChat. In this library it stores strings, booleans, numbers and ArrayBuffers, and the README positions it for app data such as global settings or a logged-in user's storage, separated by instance id.
What does mmkv default mean in react-native-mmkv?
It is the default MMKV storage ID. The README states that calling createMMKV() with no arguments creates a storage instance using the default MMKV storage ID, mmkv.default.
How do I install react-native-mmkv?
For React Native, the README gives npm install react-native-mmkv react-native-nitro-modules followed by cd ios && pod install. For Expo it uses npx expo install react-native-mmkv react-native-nitro-modules and then npx expo prebuild.
Is react-native-mmkv an alternative to AsyncStorage?
It can replace AsyncStorage for key/value use, and the difference is the mechanism: AsyncStorage goes over the Bridge asynchronously, while react-native-mmkv uses JSI and C++ NitroModules so calls are synchronous. The README claims roughly 30x faster reads based on the project's own benchmark.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/margelo-react-native-mmkv)Star history chart for your README
[](https://hysenlabs.com/projects/margelo-react-native-mmkv)Was this useful?