Async Storage 3.0 brings instance-based storage and renamed methods
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.
useAsyncStoragehook: 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:
multiGetbecomesgetMany(keys: string[]): Promise<Record<string, string | null>>. Every requested key appears in the result, withnullfor missing keys or keys with null values.multiSetbecomessetMany(entries: Record<string, string>): Promise<void>.multiRemovebecomesremoveMany(keys: string[]): Promise<void>.