Skip to content

Async Storage 3.0 brings instance-based storage and renamed methods

updated

AsyncStorage v3 introduces a few breaking changes that, according to its migration guide, aim to simplify the API and make it more consistent.

Requirements

Minimum React Native versions are 0.76 for iOS/Android, 0.78 for macOS, and 0.79 for visionOS and Windows. The other minimums listed are kotlin 2.1.0, android min sdk 24, ios min target 13 and macOS min target 12.

Installation changes

On Android, a local Maven repository must be added to android/build.gradle(.kts):

allprojects {
    repositories {
        // ... others like google(), mavenCentral()

        maven {
            url = uri(project(":react-native-async-storage_async-storage").file("local_repo"))
            // or uri("path/to/node_modules/@react-native-async-storage/async-storage/android/local_repo")
        }
    }
}

Instance-based storage

AsyncStorage is no longer a singleton. Each instance represents an isolated storage area:

// create separate storages
const userStorage = createAsyncStorage("user");
const cacheStorage = createAsyncStorage("cache");

The default export still points to the v2 implementation, so apps can keep accessing previously stored data and migrate to v3 instances incrementally.

Removals

  • Callbacks: all methods are now promise-based only.
  • Merge: the merge API has been removed because its behavior was inconsistent across platforms.
  • useAsyncStorage hook: removed due to implementation issues; it will be reintroduced in a future release with an improved design. The migration guide includes the old implementation for those who need it.

Errors

All errors thrown are now instances of AsyncStorageError, each with a type property indicating the kind of error.

Method signature changes

getItem, setItem, removeItem, getAllKeys and clear keep their v2 signatures. The batch methods have been renamed:

  • multiGet becomes getMany(keys: string[]): Promise<Record<string, string | null>>. Every requested key appears in the result, with null for missing keys or keys with null values.
  • multiSet becomes setMany(entries: Record<string, string>): Promise<void>.
  • multiRemove becomes removeMany(keys: string[]): Promise<void>.

Source: react-native-async-storage.github.io