skip to content

What changed when react-native-mmkv became a Nitro Module in v4, and what must a React Native project change to upgrade from v3?

level: middleimportance: nice to knowfreq 22%

answer

  1. add react-native-nitro-modules peer
  2. new MMKV() becomes createMMKV()
  3. delete() renamed remove()
  4. AppGroup becomes AppGroupIdentifier
  5. old architecture supported again

basics

~20 s

react-native-mmkv v4 was rewritten as a Nitro Module: install react-native-nitro-modules, replace new MMKV() with createMMKV(), rename delete() to remove(), rename the Info.plist AppGroup key to AppGroupIdentifier, and rebuild natively. It needs React Native 0.76 or newer.

solid answer

~40 s

In v4 the library was rewritten on **Nitro**, a framework for JSI-based native modules, so the JavaScript `MMKV` class is gone and instances are native hybrid objects. The upgrade is mostly mechanical: add `react-native-nitro-modules` as a dependency; change `new MMKV(config)` to `createMMKV(config)`; rename `storage.delete(key)` to `storage.remove(key)`, because `delete` is a reserved word in C++; and, for app-group sharing, rename the `Info.plist` key `AppGroup` to `AppGroupIdentifier`. Both packages contain native code, so `pod install` and a native rebuild (or prebuild and a new development build in Expo) are required. v4 needs React Native 0.76+, and unlike v3, which required the New Architecture, it also works on the old one, which matters only for apps pinned below 0.82.

go deeper

for a junior

Recall the renames: new MMKV() to createMMKV(), delete() to remove(), and that react-native-nitro-modules must be installed.

for a middle

Explain what a Nitro Module is at a high level and why the upgrade needs a native rebuild but no data migration.

for a senior

Plan the upgrade across a codebase: mechanical renames, deprecated size and recrypt, Info.plist key, rebuild, and diagnosing a missing native module.

for a principal

Weigh adopting libraries built on a shared native-module framework, including the extra peer dependency and its upgrade cadence, against their performance benefits.

## What Nitro is, briefly **Nitro Modules** (`react-native-nitro-modules`) is a framework for writing React Native native modules on top of **JSI**. A module declares its API as a TypeScript interface; Nitro generates the C++ glue, and JavaScript receives **hybrid objects** whose methods call native code synchronously. react-native-mmkv v4 declares its `MMKV` and factory interfaces this way, and the storage itself is implemented in C++. The upgrade guide lists the goals: simpler code, faster native calls, and compatibility with the old architecture again. It also switched to consuming the MMKV core through official channels, **CocoaPods** on iOS and **Gradle prefabs** on Android, so native app code can depend on MMKV core directly. ## Breaking changes, one by one | v3 | v4 | Why | |---|---|---| | `import { MMKV } from "react-native-mmkv"; new MMKV()` | `import { createMMKV } from "react-native-mmkv"; createMMKV()` | the JS class no longer exists | | `storage.delete(key)` | `storage.remove(key)` | `delete` is reserved in C++ | | `Info.plist` key `AppGroup` | `AppGroupIdentifier` | aligns with Apple's naming | | only the library installed | also `react-native-nitro-modules` | Nitro is a peer dependency | | `mode: Mode.MULTI_PROCESS` | `mode: "multi-process"` | `Mode` is a string-literal type | The hooks keep their names (`useMMKVString`, `useMMKVObject`, `useMMKV`, and so on), so most component code is untouched. ## Smaller API changes worth knowing - `storage.size` still works but is **deprecated** in favour of `storage.byteSize`. - `storage.recrypt(key)` is **deprecated** in favour of `storage.encrypt(key, type?)` and `storage.decrypt()`. - `remove(key)` returns a boolean telling you whether a key was actually removed. - Instance-level helpers `deleteMMKV(id)` and `existsMMKV(id)` delete or check whole instances by id. - `importAllFrom(other)` copies every key from another instance and returns the count. ## Upgrade steps 1. Install both packages: `npm install react-native-mmkv react-native-nitro-modules` (or `npx expo install ...` in an Expo project). 2. Replace every `new MMKV(...)` with `createMMKV(...)` and fix the type import (`MMKV` is now a type only). 3. Search for `.delete(` on storage instances and rename to `.remove(`. 4. If you share storage with extensions, rename the `Info.plist` key. 5. Run `pod install` and rebuild, or in Expo run `npx expo prebuild` and build a new development build. 6. Run the app and your test suite. The upgrade guide lists no data step: the default id (`mmkv.default`) and the documented root directory are the same in both versions, so existing instances open as before. The change is in the binding, not in what is stored. ## What stays the same Most of what an app touches day to day is unchanged, which is why the upgrade is usually an afternoon's work: - The typed read and write API: `set`, `getString`, `getNumber`, `getBoolean`, `getBuffer`, `contains`, `getAllKeys`, `clearAll`. - Most configuration fields: `id`, `path`, `encryptionKey`, `readOnly`, joined by newer ones such as `encryptionType` and `compareBeforeSet`. One detail changed: `mode` now takes a string such as `"multi-process"`, where v3 code used a `Mode` enum member (`Mode` is now exported only as a type). - The hooks and listener API: `useMMKVString` and siblings, `addOnValueChangedListener` returning a listener with `remove()`. - Synchronous behaviour: calls still return values directly on the JS thread. A practical check after upgrading is to grep the codebase for `new MMKV` and `.delete(` on storage objects; if both searches come back empty and the native build succeeds, the JavaScript side is done. ## Architecture compatibility v3 of react-native-mmkv required the **New Architecture**. v4, through Nitro, supports the old architecture again. On current React Native that distinction has faded: since **0.82** the New Architecture is the only architecture and the legacy one cannot be re-enabled. The compatibility mainly helps apps still on 0.76 to 0.81 with the old architecture enabled. The minimum is **React Native 0.76** for the library. ## Common upgrade failures - **The native module is missing at runtime**: the binary was not rebuilt after adding `react-native-nitro-modules`. - **iOS `pod install` complains about Swift pods and modular headers**: the guide traces this to an old `MMKVCore` pinned manually in the `Podfile`; removing the manual pin or updating it fixes the build. - **TypeScript errors on `new MMKV`**: the class export is gone; use `createMMKV`.

  • Does upgrading react-native-mmkv from v3 to v4 require migrating stored data?
    No. The upgrade guide lists API renames, the Nitro peer dependency and the Info.plist key, but no data step; the default id and documented root directory are unchanged, so existing instances open with the same ids and keys. The work is renaming calls, adding the dependency and rebuilding.
  • Why was delete() renamed to remove()?
    Because v4 declares the MMKV interface for Nitro, which implements it in C++, and `delete` is a reserved keyword in C++. The method therefore could not keep that name, so `remove(key)` replaced it and now returns whether a key was actually removed.

saying these in an interview costs you the question

  • Upgrading to v4 without installing react-native-nitro-modules
  • Keeping new MMKV() calls after the v4 upgrade
  • Believing the v4 upgrade needs a data migration
  • Expecting a JavaScript reload to pick up the new native code
  • Thinking v4 still requires the New Architecture, as v3 did