{"id":11784,"library":"react-native-mmkv","title":"React Native MMKV Storage","description":"react-native-mmkv is a high-performance, persistent key-value storage solution for React Native applications. It leverages Tencent's MMKV library, which is written in C++ and optimized for speed, providing significantly faster read/write operations compared to AsyncStorage. The current stable version is 4.3.1. The library maintains a rapid release cadence, with multiple minor and patch releases occurring monthly, indicating active development and responsiveness to bug fixes and feature enhancements. Key differentiators include its raw speed, native implementation via Nitro, and seamless integration with both old and new React Native architectures, supporting various data types efficiently. Version 4.x introduced a complete rewrite using Nitro and now integrates `MMKVCore` through native dependency managers like CocoaPods and Gradle, simplifying its native setup.","status":"active","version":"4.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/mrousavy/react-native-mmkv","tags":["javascript","react-native","nitro","typescript"],"install":[{"cmd":"npm install react-native-mmkv","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-mmkv","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-mmkv","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native components and hooks.","package":"react","optional":false},{"reason":"Core React Native framework dependency.","package":"react-native","optional":false},{"reason":"Required for v4.x and above, as the library is rewritten to use Nitro.","package":"react-native-nitro-modules","optional":false}],"imports":[{"note":"ESM imports are standard. CommonJS `require` syntax is not recommended and might lead to issues or incorrect typings in modern React Native projects.","wrong":"const MMKV = require('react-native-mmkv')","symbol":"MMKV","correct":"import { MMKV } from 'react-native-mmkv'"},{"note":"This hook provides reactive storage updates within React components. Ensure you import it from the library's root.","symbol":"useMMKVStorage","correct":"import { useMMKVStorage } from 'react-native-mmkv'"},{"note":"Used for advanced customization or initial setup of MMKV instances, especially when managing multiple stores or encryption.","symbol":"MMKVLoader","correct":"import { MMKVLoader } from 'react-native-mmkv'"}],"quickstart":{"code":"import { MMKV } from 'react-native-mmkv';\n\nconst storage = new MMKV();\n\n// Set values\nstorage.set('user.name', 'John Doe');\nstorage.set('user.age', 30);\nstorage.set('isLoggedIn', true);\nstorage.set('lastLoginTimestamp', Date.now());\n\nconst settings = { theme: 'dark', notifications: true };\nstorage.set('appSettings', JSON.stringify(settings));\n\n// Get values\nconst userName = storage.getString('user.name');\nconst userAge = storage.getNumber('user.age');\nconst isLoggedIn = storage.getBoolean('isLoggedIn');\nconst lastLogin = storage.getNumber('lastLoginTimestamp');\nconst appSettingsString = storage.getString('appSettings');\nconst appSettings = appSettingsString ? JSON.parse(appSettingsString) : {};\n\nconsole.log(`User: ${userName}, Age: ${userAge}, Logged In: ${isLoggedIn}`);\nconsole.log(`App Settings: ${JSON.stringify(appSettings)}`);\n\n// Delete values\nstorage.delete('user.age');\nconsole.log('User age after deletion:', storage.getNumber('user.age')); // Should be undefined or default\n\n// Clear all data\n// storage.clearAll();\n// console.log('All data cleared:', storage.getAllKeys());\n\n// Example with encrypted storage (requires a separate 'id')\nconst encryptedStorage = new MMKV({ id: 'my-encrypted-storage', encryptionKey: process.env.MMKV_ENCRYPTION_KEY ?? 'my-secret-key' });\nencryptedStorage.set('secretData', 'This is a secret!');\nconsole.log('Encrypted data:', encryptedStorage.getString('secretData'));","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=4.2.0"},{"fix":"If you are upgrading from an earlier beta or custom setup, remove `pod 'MMKVCore', :defines_modules => true` from your `ios/Podfile`.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0-beta.12"},{"fix":"Upgrade to version 4.3.1 or higher to ensure `set(ArrayBuffer)` functions correctly across all supported platforms, including Web.","message":"Using `set(ArrayBuffer)` on Web platforms was bugged in previous versions, leading to potential data corruption or unexpected behavior.","severity":"gotcha","affected_versions":"<4.3.1"},{"fix":"Upgrade to `react-native-mmkv` version 4.1.2 or higher to resolve issues related to duplicate Nitro Modules libraries.","message":"Certain Android builds experienced issues with duplicate `libNitroModules.so` libraries, leading to build failures or runtime crashes.","severity":"gotcha","affected_versions":"<4.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade `react-native-mmkv` to version 4.3.1 or higher, which includes a fix to replace `TurboReactPackage` with `BaseReactPackage` for broader compatibility.","cause":"The `TurboReactPackage` implementation was incorrect or missing a necessary fallback, particularly on specific React Native versions or architectures.","error":"Invariant Violation: A `TurboReactPackage` could not be found for 'react-native-mmkv'."},{"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.","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.","error":"Native module 'MMKV' was not found. Are you sure you've linked all of your native dependencies?"},{"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`.","cause":"You are attempting to create an `MMKV` instance with an `id` that has already been initialized in the current application lifecycle.","error":"Error: MMKV instance 'my-id' already exists!"},{"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.","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.","error":"Could not find 'react-native-nitro-modules' for platform 'android'. Make sure to add it to your dependencies and link it correctly."}],"ecosystem":"npm"}