React Native MMKV Storage

Common errors

• Invariant Violation: A `TurboReactPackage` could not be found for 'react-native-mmkv'.

  cause The `TurboReactPackage` implementation was incorrect or missing a necessary fallback, particularly on specific React Native versions or architectures.
  fix Upgrade `react-native-mmkv` to version 4.3.1 or higher, which includes a fix to replace `TurboReactPackage` with `BaseReactPackage` for broader compatibility.

• Native module 'MMKV' was not found. Are you sure you've linked all of your native dependencies?

  cause The native module for MMKV is not correctly linked or built into your application. This can happen due to caching issues, incorrect `Podfile` configuration, or outdated build artifacts.
  fix Ensure you have run `npx pod-install` (iOS) or `cd android && ./gradlew clean` then `cd ..` and rebuild your app. For v4, also verify that `react-native-nitro-modules` is correctly installed and linked.

• Error: MMKV instance 'my-id' already exists!

  cause You are attempting to create an `MMKV` instance with an `id` that has already been initialized in the current application lifecycle.
  fix Ensure that each `MMKV` instance you create has a unique `id`. If you intend to use the same storage, reuse the existing instance instead of creating a new one with the same `id`.

• Could not find 'react-native-nitro-modules' for platform 'android'. Make sure to add it to your dependencies and link it correctly.

  cause The `react-native-nitro-modules` peer dependency, essential for `react-native-mmkv` v4+, is either not installed, not correctly linked, or its version is incompatible.
  fix Install/update `react-native-nitro-modules` (`npm install react-native-nitro-modules@latest`) and ensure your `android/build.gradle` and `app/build.gradle` configurations are up-to-date according to the `react-native-mmkv` and `nitro` documentation.

Warnings

• breaking Version 4.0.0 is a complete rewrite to Nitro, changing underlying architecture and dependencies. Direct migration from v3.x to v4.x may require significant code and configuration adjustments.
  Fix: Refer to the official V4 upgrade guide on the GitHub repository for detailed migration steps and potential breaking changes. Ensure your `react-native-nitro-modules` version is compatible.
• breaking Versions 4.2.0 and higher require `react-native-nitro-modules` version 0.35.0 or higher. Older versions of Nitro Modules will cause build failures or runtime errors.
  Fix: Upgrade your `react-native-nitro-modules` package to version `0.35.0` or newer: `npm install react-native-nitro-modules@^0.35.0` or `yarn add react-native-nitro-modules@^0.35.0`.
• gotcha In `v4.0.0-beta.12`, the `MMKVCore` pod was integrated directly, removing the need to manually add `pod 'MMKVCore'` to your `Podfile`. Keeping it will cause build errors.
  Fix: If you are upgrading from an earlier beta or custom setup, remove `pod 'MMKVCore', :defines_modules => true` from your `ios/Podfile`.
• gotcha Using `set(ArrayBuffer)` on Web platforms was bugged in previous versions, leading to potential data corruption or unexpected behavior.
  Fix: Upgrade to version 4.3.1 or higher to ensure `set(ArrayBuffer)` functions correctly across all supported platforms, including Web.
• gotcha Certain Android builds experienced issues with duplicate `libNitroModules.so` libraries, leading to build failures or runtime crashes.
  Fix: Upgrade to `react-native-mmkv` version 4.1.2 or higher to resolve issues related to duplicate Nitro Modules libraries.

Install

• npm install react-native-mmkv npm
• yarn add react-native-mmkv yarn
• pnpm add react-native-mmkv pnpm

Imports

• MMKV
  wrong:

  const MMKV = require('react-native-mmkv')

  correct:

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

  ESM imports are standard. CommonJS `require` syntax is not recommended and might lead to issues or incorrect typings in modern React Native projects.
• useMMKVStorage

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

  This hook provides reactive storage updates within React components. Ensure you import it from the library's root.
• MMKVLoader

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

  Used for advanced customization or initial setup of MMKV instances, especially when managing multiple stores or encryption.

Quickstart

This quickstart demonstrates how to initialize an MMKV storage instance, store various data types (string, number, boolean, JSON objects), retrieve them, and delete specific keys. It also includes an example of setting up an encrypted storage instance.

import { MMKV } from 'react-native-mmkv';

const storage = new MMKV();

// Set values
storage.set('user.name', 'John Doe');
storage.set('user.age', 30);
storage.set('isLoggedIn', true);
storage.set('lastLoginTimestamp', Date.now());

const settings = { theme: 'dark', notifications: true };
storage.set('appSettings', JSON.stringify(settings));

// Get values
const userName = storage.getString('user.name');
const userAge = storage.getNumber('user.age');
const isLoggedIn = storage.getBoolean('isLoggedIn');
const lastLogin = storage.getNumber('lastLoginTimestamp');
const appSettingsString = storage.getString('appSettings');
const appSettings = appSettingsString ? JSON.parse(appSettingsString) : {};

console.log(`User: ${userName}, Age: ${userAge}, Logged In: ${isLoggedIn}`);
console.log(`App Settings: ${JSON.stringify(appSettings)}`);

// Delete values
storage.delete('user.age');
console.log('User age after deletion:', storage.getNumber('user.age')); // Should be undefined or default

// Clear all data
// storage.clearAll();
// console.log('All data cleared:', storage.getAllKeys());

// Example with encrypted storage (requires a separate 'id')
const encryptedStorage = new MMKV({ id: 'my-encrypted-storage', encryptionKey: process.env.MMKV_ENCRYPTION_KEY ?? 'my-secret-key' });
encryptedStorage.set('secretData', 'This is a secret!');
console.log('Encrypted data:', encryptedStorage.getString('secretData'));