@react-native-community/async-storage

What is @react-native-community/async-storage?

@react-native-community/async-storage is an asynchronous, unencrypted, persistent, key-value storage system for React Native. It is designed to store small amounts of data, such as user preferences, app settings, or other lightweight data that needs to persist across app sessions.

What are @react-native-community/async-storage's main functionalities?

Store Data

This feature allows you to store a key-value pair in the storage. The `setItem` method is used to save the data asynchronously.

async function storeData(key, value) {
  try {
    await AsyncStorage.setItem(key, value);
  } catch (e) {
    // saving error
    console.error(e);
  }
}

Retrieve Data

This feature allows you to retrieve a value by its key from the storage. The `getItem` method is used to fetch the data asynchronously.

async function retrieveData(key) {
  try {
    const value = await AsyncStorage.getItem(key);
    if (value !== null) {
      // value previously stored
      return value;
    }
  } catch (e) {
    // error reading value
    console.error(e);
  }
}

Remove Data

This feature allows you to remove a key-value pair from the storage. The `removeItem` method is used to delete the data asynchronously.

async function removeData(key) {
  try {
    await AsyncStorage.removeItem(key);
  } catch (e) {
    // remove error
    console.error(e);
  }
}

Merge Data

This feature allows you to merge an existing value with a new value for a given key. The `mergeItem` method is used to update the data asynchronously.

async function mergeData(key, value) {
  try {
    await AsyncStorage.mergeItem(key, value);
  } catch (e) {
    // merge error
    console.error(e);
  }
}

Clear All Data

This feature allows you to clear all key-value pairs from the storage. The `clear` method is used to remove all data asynchronously.

async function clearAllData() {
  try {
    await AsyncStorage.clear();
  } catch (e) {
    // clear error
    console.error(e);
  }
}

Other packages similar to @react-native-community/async-storage

react-native-mmkv

react-native-mmkv is a fast, small, and easy-to-use key-value storage library for React Native. It is based on Facebook's MMKV storage library and offers better performance and lower memory usage compared to @react-native-community/async-storage.

react-native-encrypted-storage

react-native-encrypted-storage provides a secure and encrypted storage solution for React Native applications. It uses the device's secure storage mechanisms to store data, making it more secure than @react-native-community/async-storage, which does not encrypt data.

redux-persist

redux-persist is a library that allows you to persist and rehydrate a Redux store. It can be used with various storage backends, including AsyncStorage. It is more suitable for applications that use Redux for state management and need to persist the entire state.

README

React Native Async Storage

An asynchronous, unencrypted, persistent, key-value storage system for React Native.

Supported platforms

• iOS
• Android
• Web
• MacOS
• Windows

Getting Started

Install

$ yarn add @react-native-community/async-storage

Link

• React Native 0.60+

CLI autolink feature links the module while building the app.

Use CocoaPods to add the native RNAsyncStorage to your project:

$ npx pod-install

• React Native <= 0.59

$ react-native link @react-native-community/async-storage

Note: For macOS and Windows the manual linking is currently the only linking option.

See docs for manual linking guide.

Upgrading to React Native 0.60+

React Native 0.60+ comes with autolinking feature, which automatically links Native Modules in your project. In order to get it to work, make sure you unlink Async Storage first (if you had linked it before):

$ react-native unlink @react-native-community/async-storage

Usage

AsyncStorage can only store string data, so in order to store object data you need to serialize it first. For data that can be serialized to JSON you can use JSON.stringify() when saving the data and JSON.parse() when loading the data.

Importing

import AsyncStorage from '@react-native-community/async-storage';

Storing data

setItem() is used both to add new data item (when no data for given key exists), and to modify exiting item (when previous data for given key exists).

Storing string value

const storeData = async (value) => {
  try {
    await AsyncStorage.setItem('@storage_Key', value)
  } catch (e) {
    // saving error
  }
}

Storing object value

const storeData = async (value) => {
  try {
    const jsonValue = JSON.stringify(value)
    await AsyncStorage.setItem('@storage_Key', jsonValue)
  } catch (e) {
    // saving error
  }
}

Reading data

getItem returns a promise that either resolves to stored value when data is found for given key, or returns null otherwise.

Reading string value

getData = async () => {
  try {
    const value = await AsyncStorage.getItem('@storage_Key')
    if(value !== null) {
      // value previously stored
    }
  } catch(e) {
    // error reading value
  }
}

Reading object value

getData = async () => {
  try {
    const jsonValue = await AsyncStorage.getItem('@storage_Key')
    return jsonValue != null ? JSON.parse(jsonValue) : null;
  } catch(e) {
    // error reading value
  }
}

Advanced usage

See docs for API and more examples or advanced usages.

Writing tests

Using Jest for testing? Make sure to check out docs on how to integrate it with this module.

Contribution

See the CONTRIBUTING file for how to help out.

License

MIT