English · Türkçe · 简体中文 · 日本語 · 한국어 · Español · Deutsch · Français · Português (Brasil) · Русский
A TypeScript library for keeping app data on the device in React Native and Expo apps. You
declare each value once, with a name, a default value and optionally a schema, a lifetime and a
version; then you read and write it from anywhere, or show it in a component with a hook that
re-renders when it changes. The bytes are stored by a driver you choose: MMKV, AsyncStorage,
SecureStore, localStorage or memory. It is for apps that have outgrown hand-written
JSON.parse(await AsyncStorage.getItem(...)) calls and want stored data to be checked, typed and
upgradable across app versions.
- Typed and validated — any Standard Schema (Zod, Valibot, ArkType) or a type guard checks values on write and on read; the item's type comes from the schema.
- One API over five backends — MMKV (synchronous, so hooks have the value on the first
render), AsyncStorage, SecureStore (Keychain and Keystore),
localStorageand memory, behind the sameget,set,removeanduseStorageItem. - Data that survives app updates — every record carries a schema version; migrations upgrade
old records step by step, a
legacyreader adopts values written before this library, and records from a newer app version are left untouched. - Expiry — a time to live per item or per write; a component showing an expired value falls back to the default at the moment it expires.
- Failures that do not crash the app — corrupt or invalid stored data returns the default
value and reaches
onError; error messages name the key, never the value. - Tested — 164 Vitest tests cover the codec, validation, migrations, TTL, ordering of
concurrent writes, every driver, the hook and the helpers; the example app runs on an iOS 27
simulator against the real MMKV and Keychain in
scripts/e2e-ios.sh.
1. Add the package
npm install github:muhittincamdali/ReactNativeStorage react-native-mmkv react-native-nitro-modulesThe package is installed from GitHub. MMKV is a native module: run the app with
npx expo run:ios or npx expo run:android (a development build), not in Expo Go.
2. Import the module
import { createStorage, mmkvDriver } from 'react-native-storage-toolkit';
import { useStorageItem } from 'react-native-storage-toolkit/react';3. Use it
This component, from Examples/StorageDemo/src/QuickStart.tsx,
counts presses and still shows the count after the app restarts:
import { Button } from 'react-native';
import { createMMKV } from 'react-native-mmkv';
import { createStorage, mmkvDriver } from 'react-native-storage-toolkit';
import { useStorageItem } from 'react-native-storage-toolkit/react';
const storage = createStorage({ driver: mmkvDriver(createMMKV()) });
export const pressCount = storage.item('press-count', { defaultValue: 0 });
export function PressCounter() {
const [count, setCount] = useStorageItem(pressCount);
return <Button title={`Pressed ${count} times`} onPress={() => setCount((n) => n + 1)} />;
}The package is not on the npm registry. Install it from GitHub with npm, pnpm or Yarn:
npm install github:muhittincamdali/ReactNativeStorageIt ships TypeScript sources, which Metro, Expo, Vitest and the jest-expo preset compile
directly; nothing runs at install time. Then add the backend you want to use:
| Backend | Install | Driver |
|---|---|---|
| MMKV | npx expo install react-native-mmkv react-native-nitro-modules |
mmkvDriver(createMMKV()) |
| AsyncStorage | npx expo install @react-native-async-storage/async-storage |
asyncStorageDriver(AsyncStorage) |
| SecureStore | npx expo install expo-secure-store |
secureStoreDriver(SecureStore, options) |
| Web Storage | nothing | webStorageDriver(window.localStorage, window) |
| Memory | nothing | memoryDriver() |
The samples below are compiled and run by test/readme.test.tsx,
with the memory driver in place of MMKV.
The schema runs when you write and when you read. Writing an invalid value rejects and writes
nothing; reading an invalid stored value gives the default value and calls onError.
import { z } from 'zod';
const storage = createStorage({
driver: mmkvDriver(createMMKV()),
namespace: 'app',
onError: (error) => console.warn(error.code, error.key), // the key, never the value
});
export const theme = storage.item('theme', {
schema: z.enum(['system', 'light', 'dark']),
defaultValue: 'system',
});
await theme.set('dark');
await theme.set('purple'); // rejects: StorageError VALIDATION_FAILEDuseStorageItem returns the value, a setter that accepts a value or an updater, and the item's
state. Every component that shows the item re-renders after a write, wherever it came from.
function ThemePicker() {
const [value, setValue, { status, error }] = useStorageItem(theme);
if (status === 'error') return <Text>Could not read the theme: {error?.code}</Text>;
return <Button title={`Theme: ${value}`} onPress={() => setValue('dark')} />;
}With an asynchronous driver (AsyncStorage, SecureStore) the first render has the default value
and status: 'loading'.
const draft = storage.item('draft', { defaultValue: '', ttl: 5 * 60 * 1000 });
await draft.set('Buy milk'); // gone five minutes later
const otp = storage.item<string>('otp');
await otp.set('482913', { ttl: 30_000 }); // a lifetime for one write
await storage.purgeExpired(); // removes every expired value in the namespaceRaise version and add a migration per step. Old records are upgraded when read and saved in
the new shape.
export const profile = storage.item('profile', {
schema: z.object({ first: z.string(), last: z.string() }),
version: 2,
migrations: {
2: (old) => {
const [first = '', ...rest] = String((old as { name?: unknown }).name ?? '').split(' ');
return { first, last: rest.join(' ') };
},
},
});import * as SecureStore from 'expo-secure-store';
const secure = createStorage({
driver: secureStoreDriver(SecureStore, {
keychainAccessible: SecureStore.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
}),
namespace: 'auth',
});
export const refreshToken = secure.item('refresh-token', { schema: z.string() });getOrCreateSecret(item) creates a random key once and returns it afterwards, for example to
encrypt an MMKV instance. It never overwrites a stored value it cannot use: corrupt, invalid or
expired data rejects with a StorageError and stays in place. See
Keep tokens and keys secure.
import { create } from 'zustand';
import { createJSONStorage, persist } from 'zustand/middleware';
import { toStateStorage } from 'react-native-storage-toolkit';
type Cart = { items: string[]; add: (item: string) => void };
export const useCart = create<Cart>()(
persist(
(set) => ({ items: [], add: (item) => set((cart) => ({ items: [...cart.items, item] })) }),
{
name: 'cart',
storage: createJSONStorage(() => toStateStorage(storage)),
},
),
);The same adapter works with Jotai, Redux Persist and TanStack Query persisters.
Examples/StorageDemo is an Expo SDK 58 app (React Native 0.88) that
uses every feature above with the real MMKV and SecureStore: a counter, a theme checked by Zod,
a draft with a five-minute TTL, a profile migrated from version 1, and a token created with
expo-crypto and kept in the Keychain. The screens below come from
scripts/capture-screenshots.sh, which installs the app on an
iPhone simulator and captures it.
| Light | Dark |
|---|---|
![]() |
![]() |
![]() |
![]() |
Run it yourself:
cd Examples/StorageDemo
npm install
npx expo run:ios # or: npx expo run:android, npx expo start --webReference documentation and articles:
- API reference — every export, built with TypeDoc from the sources (
npm run docsbuilds it locally intodocs/api); the Docs workflow publishes it to GitHub Pages frommain. - Error codes — what each
StorageErrorcode means.
- Move from AsyncStorage to MMKV — copy the old
keys once and read them through
legacy. - Change the shape of stored data — schemas, versions and migrations, and which values the codec keeps.
- Keep tokens and keys secure — SecureStore and an encryption key for MMKV.
- Test code that uses storage — the memory driver, a controlled clock and Jest settings.
| Toolchain | Minimum version |
|---|---|
| React | 18 (for useSyncExternalStore) |
| TypeScript, if you type-check | 5.0 |
react-native-mmkv, for mmkvDriver |
3 (version 4 needs React Native 0.76) |
| Node.js, to work on this repository | 22.12 |
The example app and the end-to-end script are tested with Expo SDK 58, React Native 0.88, Xcode 27 and the iOS 27 simulator.
useStorageItem (src/react.ts) React hook over useSyncExternalStore
│
StorageItem (src/item.ts) get / set / remove, snapshots, expiry timers
│ RecordFormat (src/record.ts) schema, versions, migrations, legacy, size limit
│ codec + envelope {rns, s, e, d} records; Date, Map, Set, bigint, NaN…
│
Storage (src/storage.ts) namespace, keys, clear, purgeExpired, onError
│ KeyStore (src/keyStore.ts) LRU cache, shared reads, ordered writes, listeners
│
StorageDriver (src/driver.ts) mmkv · async-storage · secure-store · web-storage · memory
Decisions a contributor should know:
- Drivers adapt an instance the app created and match it by shape, so the package has no runtime dependencies and supports several versions of each backend.
- Reads never throw for bad data, only for a failing driver; writes reject and write nothing.
- The key store shows a write at once and sends writes to one key in call order; when the newest write fails, it returns to the last value the backend confirmed.
- Every limit is checked at the boundary: key length and characters, value size in UTF-8 bytes, nesting depth, schema versions, TTLs (finite and within the safe integer range) and timer delays (at most 2^31-1 ms).
Planned next, tracked in the issue tracker:
- publish the package to the npm registry;
- an Android emulator run of the end-to-end script in CI;
- an optional key index for SecureStore, so
clear()can remove every secret on sign-out.
Contributions are welcome. Read the contributing guide and the code of conduct before opening a pull request. Report security issues privately as described in the security policy.
Released under the MIT license. See LICENSE.



