callstackincubator/apex-software-factory / .agents/skills/react-native-mmkv
react-native-mmkv
VerifiedFast synchronous key-value storage for React Native via react-native-mmkv (Nitro-backed). Covers creating and configuring MMKV instances, reading/writing all value types (string, number, boolean, buffer), React hooks for reactive UI, value-change listeners, encryption, AsyncStorage migration, and state-management integrations (zustand, redux-persist, jotai, react-query). Also covers storage limits, multi-process mode, and the V4 upgrade from the class-based API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
| SOURCE.md | markdown | 808 B |
| references/create-instance.md | markdown | 5.9 KB |
| references/crud-operations.md | markdown | 3.6 KB |
| references/encryption.md | markdown | 3.4 KB |
| references/hooks.md | markdown | 6.6 KB |
| references/limits-and-gotchas.md | markdown | 6.0 KB |
| references/listeners.md | markdown | 2.2 KB |
| references/migrate-from-async-storage.md | markdown | 4.4 KB |
| references/state-management.md | markdown | 6.1 KB |
| references/upgrade-v4.md | markdown | 3.7 KB |
references/migrate-from-async-storage.md
View on GitHub---
id: migrate-from-async-storage
title: Migrating from AsyncStorage to MMKV
scope: react-native-mmkv
keywords: AsyncStorage, migration, migrate, transfer, data, switch, upgrade, batch
---
# Migrating from AsyncStorage to MMKV
## Mental model
AsyncStorage is async and slow; MMKV is sync and fast. But you can't just swap the import — existing data lives in AsyncStorage's SQLite database and needs to be copied over. The migration is a one-time batch operation at app startup.
The pattern: read all keys from AsyncStorage, write them into MMKV, delete from AsyncStorage, then set a "migration done" flag so it never runs again.
## Recipe
### `storage.ts` — MMKV instance + migration function
```ts
import { createMMKV } from "react-native-mmkv";
import AsyncStorage from "@react-native-async-storage/async-storage";
export const storage = createMMKV();
const MIGRATION_KEY = "mmkv_migration_complete";
export async function migrateFromAsyncStorage(): Promise<void> {
if (storage.getBoolean(MIGRATION_KEY)) return;
console.log("Migrating from AsyncStorage to MMKV...");
const start = Date.now();
try {
const keys = await AsyncStorage.getAllKeys();
if (keys.length === 0) {
storage.set(MIGRATION_KEY, true);
return;
}
const entries = await AsyncStorage.multiGet(keys);
for (const [key, value] of entries) {
if (key == null || value == null) continue;
// Handle booleans stored as strings (common AsyncStorage pattern)
if (value === "true" || value === "false") {
storage.set(key, value === "true");
} else {
storage.set(key, value);
}
}
// Remove migrated data from AsyncStorage
await AsyncStorage.multiRemove(keys);
storage.set(MIGRATION_KEY, true);
console.log(`Migration complete in ${Date.now() - start}ms (${keys.length} keys)`);
} catch (error) {
console.error("Migration failed:", error);
throw error;
}
}
```
### `App.tsx` — run migration before app renders
```tsx
import { useEffect, useState } from "react";
import { ActivityIndicator, View } from "react-native";
import { InteractionManager } from "react-native";
import { migrateFromAsyncStorage } from "./storage";
export default function App() {
const [ready, setReady] = useState(false);
useEffect(() => {
InteractionManager.runAfterInteractions(async () => {
try {
await migrateFromAsyncStorage();
} catch {
// TODO: decide on fallback — retry, ignore, or crash
} finally {
setReady(true);
}
});
}, []);
if (!ready) {
return (
<View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
<ActivityIndicator />
</View>
);
}
return <MainApp />;
}
```
### Swapping calls throughout the codebase
After migration, replace all AsyncStorage usage:
```ts
// BEFORE
const value = await AsyncStorage.getItem("user.name");
await AsyncStorage.setItem("user.name", "Marc");
// AFTER
const value = storage.getString("user.name");
storage.set("user.name", "Marc");
```
Key differences:
- No `await` — everything is synchronous
- `getItem` → `getString` / `getNumber` / `getBoolean` (type-specific)
- `setItem` → `set` (accepts string, number, boolean, ArrayBuffer)
- `removeItem` → `remove`
- `multiGet` / `multiSet` → loop with `set` / `getString` (still fast because synchronous)
- `clear` → `clearAll`
## Gotchas
- **AsyncStorage stores everything as strings.** Numbers come back as `"42"`, booleans as `"true"`. Parse them during migration if you want typed values in MMKV.
- **`null` vs `undefined`.** AsyncStorage's `getItem` returns `null` for missing keys; MMKV's getters return `undefined`. Update any `value === null` checks to `value === undefined`.
- **Remove migration code eventually.** Once all users have upgraded, the migration path is dead code. Add a TODO to remove it.
- **Don't migrate on every launch.** The `MIGRATION_KEY` flag is critical — without it, you'll re-run the (now empty) migration on every cold start.
- **Error handling is your decision.** If migration fails partway, some keys are in MMKV and some are still in AsyncStorage. Decide whether to retry, crash, or continue.
## Pointers
- Official migration guide: [MIGRATE_FROM_ASYNC_STORAGE.md](https://github.com/mrousavy/react-native-mmkv/blob/main/docs/MIGRATE_FROM_ASYNC_STORAGE.md)
- Related: [create-instance.md](./create-instance.md), [crud-operations.md](./crud-operations.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |