AsyncStorage: React Native's Async Key-Value Store

WHY IT EXISTS: Mobile apps lose all JavaScript state when the OS kills them or the user swipes them away. React Native needed a minimal, always-available mechanism to survive restarts without forcing developers to wire up SQLite or platform-specific native code on day one. AsyncStorage fills that gap by providing a simple asynchronous key-value interface backed by persistent disk storage on both iOS and Android.

THE MENTAL MODEL: Think of AsyncStorage as a junk drawer in your kitchen. You toss in labeled envelopes containing handwritten notes. There is no schema, no tables, and no queries beyond hand me the envelope labeled X. It is eventually consistent, unencrypted, and best suited for small bits of data you can afford to lose if the user clears app storage.

HOW IT WORKS: Under the hood, React Native bridges calls to native modules. On iOS it historically used serialized dictionaries backed by property list files, while on Android it leans on SQLite or SharedPreferences depending on the implementation. The JavaScript API is promise-based. You call setItem with a key and a string value, getItem to retrieve, or multiGet for batch reads. Every value must be a string, so objects are typically run through JSON stringify before storage and JSON parse on retrieval. Operations are asynchronous because disk I/O blocks threads, and the bridge marshals data across the JS-native boundary.

WHEN TO USE IT: Reach for AsyncStorage when you need lightweight persistence without adding dependencies. Good fits include authentication tokens, boolean feature flags, cached API JSON under a few megabytes, or user preference strings. It is also useful for offline-first UI state like whether the user has seen a tutorial, where latency tolerance is high and the data footprint is tiny.

WHEN NOT TO USE IT: Do not use AsyncStorage as a relational database, a search index, or a secure vault. It lacks encryption, indexing, and atomic transactions across multiple keys. If you are storing financial data, health records, or passwords, use the iOS Keychain or Android Keystore via a dedicated secure storage library instead. Likewise, if your dataset grows beyond a few megabytes or requires complex querying, migrate to SQLite, Realm, or a server-side cache.

ONE CANONICAL EXAMPLE: A common pattern is persisting a JWT login token. On successful authentication, you stringify the token and call AsyncStorage setItem with the key userToken and the token string. In your root navigator, you read it back with getItem during app launch to decide whether to show the login screen or the home screen. If the user logs out, you call removeItem or clear to wipe it. This keeps the user logged in across restarts while keeping the implementation to a few lines of plain JavaScript.