repository·main·Indexed 26 days ago
https://github.com/react-native-async-storage/async-storageAn asynchronous, unencrypted, persistent key-value storage solution for React Native applications. It is compatible with the Web Storage API and supports multi-database operations via SQLite on Android, iOS, and macOS, and IndexedDB on Web. The library provides scoped storage via createAsyncStorage, batch operations, and specialized error handling through AsyncStorageError.
The Android shared-storage module is a Kotlin Multiplatform (KMP) library that serves as the core backend. It is distributed via a maven local repository. To build the SDK and make the artifact available in your local maven repository (~/.m2), run the following command:
yarn build:androidmergeItem functionality, and the removal of the useAsyncStorage hook. Errors now use a standardized AsyncStorageError type with a type property.To automatically replace the native module with the built-in in-memory mock for all tests, create a manual mock file at the following path:
__mocks__/@react-native-async-storage/async-storage.js
Inside that file, export the built-in Jest mock implementation.
module.exports = require("@react-native-async-storage/async-storage/jest");Because @react-native-async-storage/async-storage is shipped as ESM source, you must configure Jest to transform it. Add the package to your transformIgnorePatterns in your Jest configuration file to prevent Jest from ignoring it during the transformation process.
transformIgnorePatterns: [
'node_modules/(?!@react-native-async-storage/)',
],For iOS and macOS brownfield applications, you can access the shared storage layer from Swift or Objective-C using the StorageRegistry singleton. This allows native code to read from and write to the same storage used by the React Native layer.
Access the storage by calling StorageRegistry.shared.getStorage(dbName: "name"). Use setValues and getValues with Entry objects to manage data. Note that these operations are typically asynchronous and should be handled within a Task or similar concurrency construct.
import AsyncStorage
import SharedAsyncStorage
// access shared storage via StorageRegistry
let storage: SharedStorage = StorageRegistry.shared.getStorage(dbName: "my-users")
Task {
storage.setValues([Entry(key: "email", value: "john@example.com")])
let values = storage.getValues(keys: ["email"])
print("Stored email: \(values.first?.value ?? "none")")
}To apply the plugin, add @react-native-async-storage/expo-with-async-storage to the plugins array in your app.json file. After updating the configuration, you must run expo prebuild or eas build to apply the changes to your native project files.
Requirement: This plugin requires expo >= 53.
{
"expo": {
"plugins": [
"@react-native-async-storage/expo-with-async-storage"
]
}
}For iOS or macOS platforms, you must install the CocoaPods dependencies by running pod install from within the macos/ios directory of your project.
# inside macos/ios directory
pod installInstall the Async Storage package using npm or yarn depending on your project's package manager.
# Using npm
npm install @react-native-async-storage/async-storage
# Using yarn
yarn add @react-native-async-storage/async-storageThe shared-storage module for Apple platforms is distributed as an xcframework containing both Debug and Release binaries. To build the framework, run the following command. The resulting artifact will be moved to packages/async-storage/apple/Frameworks for distribution.
yarn build:applecreateAsyncStorage(databaseName), the databaseName determines the physical location and structure of the underlying database file. This mechanism scopes each storage instance by name, preventing data leakage between different instances.If you are using an Expo managed or bare project and need to automatically configure @react-native-async-storage/async-storage, use the @react-native-async-storage/expo-with-async-storage config plugin.
Note: This plugin is no longer required if you are using @react-native-async-storage/async-storage version 3.1.0+, as the Android build artifacts are now provided via Maven Central automatically.
yarn add @react-native-async-storage/expo-with-async-storageAsyncStorage only stores strings. To store complex data types like objects or arrays, you must serialize them using JSON.stringify before writing and JSON.parse when reading them back.
import { createAsyncStorage } from "@react-native-async-storage/async-storage";
const storage = createAsyncStorage("my-app");
// Storing an object
const user = { name: "John", age: 30 };
await storage.setItem("user", JSON.stringify(user));
// Reading it back
const raw = await storage.getItem("user");
const user = raw ? JSON.parse(raw) : null;