react-native-mmkv
Fast 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.
- Installs
- 891
- Last 24h
- +51
- Trending rank
- #3302
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/margelo/react-native-skills --skill react-native-mmkv- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads react-native-mmkv automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
react-native-mmkv
A focused reference for AI coding assistants working in a project that uses react-native-mmkv. Answer using the real APIs from this library — not invented ones — by routing to the matching references/*.md file below.
Mental model
react-native-mmkv is a high-performance, synchronous key-value storage library for React Native, backed by Tencent's MMKV C++ engine via Nitro Modules (JSI). It is ~30x faster than AsyncStorage.
The three things that trip people up:
- Everything is synchronous. No
await, no Promises.storage.getString('key')returns the value immediately. This is the whole point — MMKV memory-maps files and reads/writes in-process. - It's a key-value store, not a database. All data is cached in memory. Keep total size under ~100 MB; for larger datasets use react-native-nitro-sqlite or WatermelonDB. There is no fixed storage limit — but memory warnings will fire if you go too large.
- V4 is a breaking rewrite. The constructor changed from
new MMKV()tocreateMMKV(),.delete()became.remove(), andreact-native-nitro-modulesis now a required peer dependency. See the upgrade guide.
V4 requires React Native 0.75+. It works on both the New Architecture and the old architecture (Nitro is backwards compatible).
Routing table — problem to reference
Load the matching file from references/ before writing code. Each reference cites real APIs from the library.
| User is asking about… | Read |
|---|---|
Creating an MMKV instance, configuration options (id, path, encryptionKey, mode, readOnly, compareBeforeSet), the createMMKV() factory | references/create-instance.md |
Getting/setting values, all data types (string, number, boolean, buffer, objects via JSON), key management (contains, getAllKeys, remove, clearAll), size, trim, importAllFrom | references/crud-operations.md |
React hooks (useMMKVString, useMMKVNumber, useMMKVBoolean, useMMKVBuffer, useMMKVObject, useMMKV, useMMKVListener, useMMKVKeys), reactive UI | references/hooks.md |
Listening for value changes outside of React, addOnValueChangedListener, cleaning up listeners | references/listeners.md |
Encryption (encrypt, decrypt, recrypt), AES-128 vs AES-256, encryptionKey config | references/encryption.md |
| Migrating from AsyncStorage, data transfer pattern, completion flag | references/migrate-from-async-storage.md |
zustand persist middleware, redux-persist, jotai atomWithMMKV, react-query persister, MobX | references/state-management.md |
V4 upgrade, breaking changes from V3, new MMKV() → createMMKV(), .delete() → .remove() | references/upgrade-v4.md |
| Storage size limits, memory warnings, when to use a database instead | references/limits-and-gotchas.md |
If the question doesn't match any row, read references/create-instance.md first — most setup questions start there.
Installation
npm install react-native-mmkv react-native-nitro-modules
cd ios && pod install
Expo:
npx expo install react-native-mmkv react-native-nitro-modules
npx expo prebuild
After install, rebuild the app. No additional native wiring is required.
Quick reference — full MMKV instance API
import { createMMKV, existsMMKV, deleteMMKV } from 'react-native-mmkv'
const storage = createMMKV({ id: 'my-store' })
// Properties (read-only)
storage.id // string
storage.length // number of keys
storage.byteSize // total file size in bytes
storage.size // (deprecated — use byteSize)
storage.isReadOnly // boolean
storage.isEncrypted // boolean
// Write
storage.set('key', 'string' | 42 | true | arrayBuffer)
// Read
storage.getString('key') // string | undefined
storage.getNumber('key') // number | undefined
storage.getBoolean('key') // boolean | undefined
storage.getBuffer('key') // ArrayBuffer | undefined
// Keys
storage.contains('key') // boolean
storage.getAllKeys() // string[]
storage.remove('key') // boolean (NOTE: was .delete() in V3)
storage.clearAll() // void
// Encryption
storage.encrypt('password')
storage.encrypt('password', 'AES-256')
storage.decrypt()
storage.recrypt('newPassword' | undefined) // (deprecated — use encrypt()/decrypt())
// Maintenance
storage.trim() // free unused space
storage.importAllFrom(otherStorage) // returns count imported
// Listeners
const sub = storage.addOnValueChangedListener((key) => { ... })
sub.remove()
// Static helpers
existsMMKV('my-store') // boolean
deleteMMKV('my-store') // boolean
Testing
A mocked MMKV instance is automatically used when testing with Jest or Vitest. Use createMMKV() as normal in tests — no manual mocking needed.
Verifying the skill is loaded
Good test questions:
- "How do I persist zustand state with MMKV?" → should produce a
StateStorageadapter usingstorage.set,storage.getString,storage.remove— not AsyncStorage wrappers. - "How do I migrate from AsyncStorage to MMKV?" → should show the batch-copy pattern with a completion flag, not a drop-in replacement.
- "What's the storage limit?" → should explain there's no fixed limit, but data is memory-mapped so keep it under ~100 MB; use SQLite for larger datasets.
References
| File | Description |
|---|---|
| create-instance.md | createMMKV() factory, all configuration options |
| crud-operations.md | Set/get all types, key management, objects, buffers |
| hooks.md | All React hooks for reactive MMKV usage |
| listeners.md | addOnValueChangedListener, cleanup |
| encryption.md | Encrypt/decrypt instances, AES options |
| migrate-from-async-storage.md | Full migration pattern from AsyncStorage |
| state-management.md | zustand, redux-persist, jotai, react-query, MobX |
| upgrade-v4.md | V3 → V4 breaking changes and migration |
| limits-and-gotchas.md | Storage limits, multi-process, logging, common pitfalls |
Problem → Reference Mapping
| Problem | Reference | Action |
|---|---|---|
| Don't know where to start | create-instance.md | Create instance with createMMKV() |
| Need reactive UI updates | hooks.md | Use useMMKVString / useMMKVObject etc. |
| Encrypting sensitive data | encryption.md | Call storage.encrypt(key) |
| App uses AsyncStorage, want to switch | migrate-from-async-storage.md | Batch migrate then swap calls |
| Zustand/Redux/Jotai persistence | state-management.md | Wire adapter for your state lib |
| Upgrading from V3 to V4 | upgrade-v4.md | new MMKV() → createMMKV(), .delete() → .remove() |
| Storage growing too large | limits-and-gotchas.md | Trim or move to SQLite |
| Multi-process data sharing | limits-and-gotchas.md | Set mode: 'multi-process' |
FAQ
What does the react-native-mmkv skill do?
Fast 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.
How do I install react-native-mmkv?
Run npx skills add https://github.com/margelo/react-native-skills --skill react-native-mmkv in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/react-native-mmkv/ (personal) or .claude/skills/react-native-mmkv/ (project).
Which AI agents can use react-native-mmkv?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is react-native-mmkv safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains react-native-mmkv?
It is published by margelo in margelo/react-native-skills. It has 891 recorded installs.
More from margelo/react-native-skills
build-nitro-modules
margelo/react-native-skills
Builds and designs React Native Nitro Modules with Nitrogen, HybridObject TypeScript specs, Nitro View components, generated native implementations, zero-copy and native-state APIs, Swift/Kotlin/C++ bindings, example apps, and testing. Use when creating a Nitro Module, adding or reviewing HybridObjects, building a Nitro View (HybridView) component, designing Nitro-specific public APIs, implementing native functionality, or setting up the nitrogen codegen pipeline. Pair with api-design for general library API shape.
react-native-vision-camera
margelo/react-native-skills
Best-practices guide for React Native VisionCamera v5 setup, migration, capture, controls, outputs, and basic frame processing. Use the separate react-native-vision-camera-realtime skill for production low-latency GPU, ML, CV, Skia or WebGPU pipelines and frame-coupled overlays.
nitro-fetch
margelo/react-native-skills
Fast native networking primitives for React Native built on Nitro Modules — react-native-nitro-fetch, react-native-nitro-websockets, and react-native-nitro-text-decoder. Covers the fetch API, global replacement, prefetching and cold-start cache warming, the NitroWebSocket class and pre-warming, migrating from React Native's built-in WebSocket, the in-process NetworkInspector, native Perfetto / Instruments tracing, the native TextDecoder, and plugging nitro-fetch into axios via a custom adapter.
api-design
margelo/react-native-skills
Design and review predictable public APIs for TypeScript, JavaScript, React, and React Native libraries. Use when shaping exported functions, classes, hooks, options objects, event and listener APIs, error behavior, naming, cross-platform abstractions, or JS-only packages. Pair with build-nitro-modules when the library is backed by Nitro.
swift
margelo/react-native-skills
Design, implement, and review Swift APIs and Apple-platform code. Use when working on .swift files, Swift types, Foundation or AVFoundation APIs, DispatchQueue, async/await, Task, actors, MainActor, thread-affine state, or Swift-backed React Native Nitro Module implementations.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance 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.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.