react-native-mmkv

What is react-native-mmkv?

react-native-mmkv is a fast, small, and easy-to-use key-value storage library for React Native. It leverages Facebook's MMKV storage library to provide efficient and secure storage solutions for mobile applications.

What are react-native-mmkv's main functionalities?

Basic Key-Value Storage

This feature allows you to store and retrieve basic key-value pairs. The code sample demonstrates how to set and get a string value using MMKV.

import MMKVStorage from 'react-native-mmkv-storage';

const MMKV = new MMKVStorage.Loader().initialize();

// Set a value
MMKV.setString('username', 'john_doe');

// Get a value
const username = MMKV.getString('username');
console.log(username); // Output: john_doe

Object Storage

This feature allows you to store and retrieve objects. The code sample demonstrates how to set and get an object using MMKV.

import MMKVStorage from 'react-native-mmkv-storage';

const MMKV = new MMKVStorage.Loader().initialize();

const user = { name: 'John Doe', age: 30 };

// Set an object
MMKV.setMap('user', user);

// Get an object
const storedUser = MMKV.getMap('user');
console.log(storedUser); // Output: { name: 'John Doe', age: 30 }

Encryption

This feature allows you to store data securely using encryption. The code sample demonstrates how to set and get an encrypted string value using MMKV.

import MMKVStorage from 'react-native-mmkv-storage';

const MMKV = new MMKVStorage.Loader().withEncryption().initialize();

// Set a value
MMKV.setString('secret', 'my_secret_value');

// Get a value
const secret = MMKV.getString('secret');
console.log(secret); // Output: my_secret_value

Multi-Instance Support

This feature allows you to create multiple instances of storage, which can be useful for separating different types of data. The code sample demonstrates how to set and get values from different instances using MMKV.

import MMKVStorage from 'react-native-mmkv-storage';

const userStorage = new MMKVStorage.Loader().withInstanceID('user').initialize();
const settingsStorage = new MMKVStorage.Loader().withInstanceID('settings').initialize();

// Set values in different instances
userStorage.setString('username', 'john_doe');
settingsStorage.setBool('darkMode', true);

// Get values from different instances
const username = userStorage.getString('username');
const darkMode = settingsStorage.getBool('darkMode');
console.log(username); // Output: john_doe
console.log(darkMode); // Output: true

Other packages similar to react-native-mmkv

react-native-async-storage

react-native-async-storage is a simple, unencrypted, asynchronous, persistent, key-value storage system that is global to the app. It is more widely used and has a larger community but lacks the performance and encryption features of react-native-mmkv.

react-native-sensitive-info

react-native-sensitive-info provides secure storage for sensitive data, such as login credentials. It uses the device's secure storage mechanisms (Keychain on iOS and Keystore on Android). While it offers strong security, it may not be as fast as react-native-mmkv for general key-value storage.

redux-persist

redux-persist is a library used to persist and rehydrate a Redux store. It supports various storage backends, including AsyncStorage. While it is not a direct competitor, it can be used for state persistence in applications using Redux, offering more flexibility in terms of storage backends.

README

中文版本请参看这里

MMKV is an efficient, small, easy-to-use mobile key-value storage framework used in the WeChat application. It's currently available on Android, iOS/macOS, Windows, POSIX and HarmonyOS NEXT.

MMKV for Android

Features

• Efficient. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of Android to achieve the best performance.

  • Multi-Process concurrency: MMKV supports concurrent read-read and read-write access between processes.

• Easy-to-use. You can use MMKV as you go. All changes are saved immediately, no sync, no apply calls needed.

• Small.

  • A handful of files: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
  • About 50K in binary size: MMKV adds about 50K per architecture on App size, and much less when zipped (APK).

Getting Started

Installation Via Maven

Add the following lines to build.gradle on your app module:

dependencies {
    implementation 'com.tencent:mmkv:1.3.5'
    // replace "1.3.5" with any available version
}

For other installation options, see Android Setup.

Quick Tutorial

You can use MMKV as you go. All changes are saved immediately, no sync, no apply calls needed.
Setup MMKV on App startup, say your Application class, add these lines:

public void onCreate() {
    super.onCreate();

    String rootDir = MMKV.initialize(this);
    System.out.println("mmkv root: " + rootDir);
    //……
}

MMKV has a global instance, that can be used directly:

import com.tencent.mmkv.MMKV;
    
MMKV kv = MMKV.defaultMMKV();

kv.encode("bool", true);
boolean bValue = kv.decodeBool("bool");

kv.encode("int", Integer.MIN_VALUE);
int iValue = kv.decodeInt("int");

kv.encode("string", "Hello from mmkv");
String str = kv.decodeString("string");

MMKV also supports Multi-Process Access. Full tutorials can be found here Android Tutorial.

Performance

Writing random int for 1000 times, we get this chart:

For more benchmark data, please refer to our benchmark.

MMKV for iOS/macOS

Features

• Efficient. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of iOS/macOS to achieve the best performance.

• Easy-to-use. You can use MMKV as you go, no configurations are needed. All changes are saved immediately, no synchronize calls are needed.

• Small.

  • A handful of files: MMKV contains encode/decode helpers and mmap logics and nothing more. It's really tidy.
  • Less than 30K in binary size: MMKV adds less than 30K per architecture on App size, and much less when zipped (IPA).

Getting Started

Installation Via CocoaPods:

1. Install CocoaPods;
2. Open the terminal, cd to your project directory, run pod repo update to make CocoaPods aware of the latest available MMKV versions;
3. Edit your Podfile, add pod 'MMKV' to your app target;
4. Run pod install;
5. Open the .xcworkspace file generated by CocoaPods;
6. Add #import <MMKV/MMKV.h> to your source file and we are done.

For other installation options, see iOS/macOS Setup.

Quick Tutorial

You can use MMKV as you go, no configurations are needed. All changes are saved immediately, no synchronize calls are needed. Setup MMKV on App startup, in your -[MyApp application: didFinishLaunchingWithOptions:], add these lines:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // init MMKV in the main thread
    [MMKV initializeMMKV:nil];

    //...
    return YES;
}

MMKV has a global instance, that can be used directly:

MMKV *mmkv = [MMKV defaultMMKV];
    
[mmkv setBool:YES forKey:@"bool"];
BOOL bValue = [mmkv getBoolForKey:@"bool"];
    
[mmkv setInt32:-1024 forKey:@"int32"];
int32_t iValue = [mmkv getInt32ForKey:@"int32"];
    
[mmkv setString:@"hello, mmkv" forKey:@"string"];
NSString *str = [mmkv getStringForKey:@"string"];

MMKV also supports Multi-Process Access. Full tutorials can be found here.

Performance

Writing random int for 10000 times, we get this chart:

For more benchmark data, please refer to our benchmark.

MMKV for Windows

Features

• Efficient. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of Windows to achieve the best performance.

  • Multi-Process concurrency: MMKV supports concurrent read-read and read-write access between processes.

• Easy-to-use. You can use MMKV as you go. All changes are saved immediately, no save, no sync calls are needed.

• Small.

  • A handful of files: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
  • About 10K in binary size: MMKV adds about 10K on application size, and much less when zipped.

Getting Started

Installation Via Source

1. Getting source code from git repository:

   git clone https://github.com/Tencent/MMKV.git
   

2. Add Core/core.vcxproj to your solution;

3. Add MMKV project to your project's dependencies;

4. Add $(OutDir)include to your project's C/C++ -> General -> Additional Include Directories;

5. Add $(OutDir) to your project's Linker -> General -> Additional Library Directories;

6. Add mmkv.lib to your project's Linker -> Input -> Additional Dependencies;

7. Add #include <MMKV/MMKV.h> to your source file and we are done.

note:

1. MMKV is compiled with MT/MTd runtime by default. If your project uses MD/MDd, you should change MMKV's setting to match your project's (C/C++ -> Code Generation -> Runtime Library), or vice versa.
2. MMKV is developed with Visual Studio 2017, change the Platform Toolset if you use a different version of Visual Studio.

For other installation options, see Windows Setup.

Quick Tutorial

You can use MMKV as you go. All changes are saved immediately, no sync, no save calls needed.
Setup MMKV on App startup, say in your main(), add these lines:

#include <MMKV/MMKV.h>

int main() {
    std::wstring rootDir = getYourAppDocumentDir();
    MMKV::initializeMMKV(rootDir);
    //...
}

MMKV has a global instance, that can be used directly:

auto mmkv = MMKV::defaultMMKV();

mmkv->set(true, "bool");
std::cout << "bool = " << mmkv->getBool("bool") << std::endl;

mmkv->set(1024, "int32");
std::cout << "int32 = " << mmkv->getInt32("int32") << std::endl;

mmkv->set("Hello, MMKV for Windows", "string");
std::string result;
mmkv->getString("string", result);
std::cout << "string = " << result << std::endl;

MMKV also supports Multi-Process Access. Full tutorials can be found here Windows Tutorial.

MMKV for POSIX

Features

• Efficient. MMKV uses mmap to keep memory synced with files, and protobuf to encode/decode values, making the most of POSIX to achieve the best performance.

  • Multi-Process concurrency: MMKV supports concurrent read-read and read-write access between processes.

• Easy-to-use. You can use MMKV as you go. All changes are saved immediately, no save, no sync calls are needed.

• Small.

  • A handful of files: MMKV contains process locks, encode/decode helpers and mmap logics, and nothing more. It's really tidy.
  • About 7K in binary size: MMKV adds about 7K on application size, and much less when zipped.

Getting Started

Installation Via CMake

1. Getting source code from the git repository:

   git clone https://github.com/Tencent/MMKV.git
   

2. Edit your CMakeLists.txt, add those lines:

   add_subdirectory(mmkv/POSIX/src mmkv)
   target_link_libraries(MyApp
       mmkv)
   

3. Add #include "MMKV.h" to your source file and we are done.

For other installation options, see POSIX Setup.

Quick Tutorial

You can use MMKV as you go. All changes are saved immediately, no sync, no save calls needed.
Setup MMKV on App startup, say in your main(), add these lines:

#include "MMKV.h"

int main() {
    std::string rootDir = getYourAppDocumentDir();
    MMKV::initializeMMKV(rootDir);
    //...
}

MMKV has a global instance, that can be used directly:

auto mmkv = MMKV::defaultMMKV();

mmkv->set(true, "bool");
std::cout << "bool = " << mmkv->getBool("bool") << std::endl;

mmkv->set(1024, "int32");
std::cout << "int32 = " << mmkv->getInt32("int32") << std::endl;

mmkv->set("Hello, MMKV for Windows", "string");
std::string result;
mmkv->getString("string", result);
std::cout << "string = " << result << std::endl;

MMKV also supports Multi-Process Access. Full tutorials can be found here POSIX Tutorial.

MMKV for HarmonyOS NEXT

Features

• Efficient. MMKV uses mmap to keep memory synced with file, and protobuf to encode/decode values, making the most of native platform to achieve best performance.

  • Multi-Process concurrency: MMKV supports concurrent read-read and read-write access between processes.

• Easy-to-use. You can use MMKV as you go. All changes are saved immediately, no sync, no flush calls needed.

• Small.

  • A handful of files: MMKV contains process locks, encode/decode helpers and mmap logics and nothing more. It's really tidy.
  • About 600K in binary size: MMKV adds about 600K per architecture on App size, and much less when zipped (HAR/HAP).

Getting Started

Installation via OHPM:

ohpm install @tencent/mmkv

Quick Tutorial

You can use MMKV as you go. All changes are saved immediately, no sync, no apply calls needed.
Setup MMKV on App startup, say your EntryAbility.onCreate() function, add these lines:

import { MMKV } from '@tencent/mmkv';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let appCtx = this.context.getApplicationContext();
    let mmkvRootDir = MMKV.initialize(appCtx);
    console.info('mmkv rootDir: ', mmkvRootDir);
    ……
  }

MMKV has a global instance, that can be used directly:

import { MMKV } from '@tencent/mmkv';
    
let mmkv = MMKV.defaultMMKV();
mmkv.encodeBool('bool', true);
console.info('bool = ', mmkv.decodeBool('bool'));
    
mmkv.encodeInt32('int32', Math.pow(2, 31) - 1);
console.info('max int32 = ', mmkv.decodeInt32('int32'));
    
mmkv.encodeInt64('int', BigInt(2**63) - BigInt(1));
console.info('max int64 = ', mmkv.decodeInt64('int'));
    
let str: string = 'Hello OpenHarmony from MMKV';
mmkv.encodeString('string', str);
console.info('string = ', mmkv.decodeString('string'));

let arrayBuffer: ArrayBuffer = StringToArrayBuffer('Hello OpenHarmony from MMKV with bytes');
mmkv.encodeBytes('bytes', arrayBuffer);
let bytes = mmkv.decodeBytes('bytes');
console.info('bytes = ', ArrayBufferToString(bytes));

As you can see, MMKV is quite easy to use. For the full documentation, see HarmonyOS NEXT Tutorial.

License

MMKV is published under the BSD 3-Clause license. For details check out the LICENSE.TXT.

Change Log

Check out the CHANGELOG.md for details of change history.

Contributing

If you are interested in contributing, check out the CONTRIBUTING.md, also join our Tencent OpenSource Plan.

To give clarity of what is expected of our members, MMKV has adopted the code of conduct defined by the Contributor Covenant, which is widely used. And we think it articulates our values well. For more, check out the Code of Conduct.

FAQ & Feedback

Check out the FAQ first. Should there be any questions, don't hesitate to create issues.

Personal Information Protection Rules

User privacy is taken very seriously: MMKV does not obtain, collect or upload any personal information. Please refer to the MMKV SDK Personal Information Protection Rules for details.