Skip to content

callstackincubator/apex-software-factory / .agents/skills/react-native-mmkv

react-native-mmkv

Verified

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.

references/create-instance.md

View on GitHub
---
id: create-instance
title: Creating and configuring MMKV instances
scope: react-native-mmkv
keywords: createMMKV, configuration, id, path, encryptionKey, encryptionType, mode, readOnly, compareBeforeSet, multi-process, existsMMKV, deleteMMKV
---

# Creating and configuring MMKV instances

## Mental model

MMKV instances are created with the `createMMKV()` factory function. Each instance maps to a single file on disk identified by its `id`. The default instance uses `'mmkv.default'`. Multiple instances can coexist — a common pattern is one global instance and one per-user instance.

> **V4 change:** `new MMKV()` was replaced by `createMMKV()`. See [upgrade-v4.md](./upgrade-v4.md).

## Imports

```ts
import { createMMKV, existsMMKV, deleteMMKV } from "react-native-mmkv";
```

## Recipes

### Default instance (simplest)

```ts
export const storage = createMMKV();
```

### Customized instance

```ts
export const storage = createMMKV({
  id: `user-${userId}-storage`,
  path: `${USER_DIRECTORY}/storage`,
  encryptionKey: "hunter2",
  encryptionType: "AES-256",
  mode: "multi-process",
  readOnly: false,
  compareBeforeSet: false,
});
```

### Per-user storage pattern

```ts
function createUserStorage(userId: string) {
  return createMMKV({
    id: `user-${userId}-storage`,
    encryptionKey: userEncryptionKey,
  });
}
```

### Check if an instance exists on disk

```ts
const exists = existsMMKV("my-instance");
```

### Delete an instance from disk

```ts
const wasDeleted = deleteMMKV("my-instance");
```

## Configuration options

| Option             | Type                                  | Default            | Description                                                                                                                               |
| ------------------ | ------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                              | `'mmkv.default'`   | Unique identifier for this instance. Maps to a file on disk.                                                                              |
| `path`             | `string`                              | `undefined`        | Custom root directory for the storage file. When unset, MMKV uses `$(Documents)/mmkv/` (or the App Group directory on iOS if configured). |
| `encryptionKey`    | `string`                              | `undefined`        | Encryption key. Enables AES encryption when set.                                                                                          |
| `encryptionType`   | `'AES-128' \| 'AES-256'`              | `'AES-128'`        | Encryption algorithm. Only used when `encryptionKey` is set.                                                                              |
| `mode`             | `'single-process' \| 'multi-process'` | `'single-process'` | Set to `'multi-process'` if another process (e.g. a widget or app extension) reads/writes the same instance.                              |
| `readOnly`         | `boolean`                             | `false`            | When `true`, all write operations throw.                                                                                                  |
| `compareBeforeSet` | `boolean`                             | `false`            | When `true`, compares the new value with the existing one before writing. Avoids unnecessary disk writes.                                 |

## iOS App Groups

To share MMKV data between your main app and an extension (widget, share extension, etc.), configure an App Group:

1. Add the `AppGroupIdentifier` key to your `Info.plist` with the group ID (e.g. `group.com.myapp`).
2. Set `path` to the shared container directory.

> **V4 change:** The key was renamed from `AppGroup` to `AppGroupIdentifier`.

## Rule of Thumb — how many instances?

| App size             | Recommended instances                |
| -------------------- | ------------------------------------ |
| Small / simple       | 1 (default)                          |
| Medium               | 2–3 (e.g., usercache, auth, session) |
| Large / multi-module | 3–5, grouped by domain               |

**Why not more?** Each MMKV instance memory-maps its own file. More instances means more mmap'd regions held open simultaneously, which increases the app's resident memory footprint. On memory-constrained devices this can trigger OS memory warnings or even OOM kills — especially if several instances are large. Consolidating related keys into fewer instances keeps the mmap count low and makes `trim()` / `clearAll()` operations simpler. Only split into a separate instance when you have a clear reason (different encryption keys, different lifecycle like per-user vs global, or App Group sharing).

## Gotchas

- **Same `id` = same file.** Two `createMMKV({ id: 'foo' })` calls return instances pointing to the same underlying file. This is fine — but encrypting one will affect all references.
- **`path` must exist.** MMKV does not create intermediate directories. Ensure the path exists before creating the instance.
- **`readOnly` + write = throw.** If you set `readOnly: true`, calling `set()`, `remove()`, or `clearAll()` will throw an error.
- **`compareBeforeSet` has a cost.** It reads the current value before every write. For high-frequency writes, this can be slower than just writing.

## Pointers

- Source: [createMMKV.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/createMMKV/createMMKV.ts)
- Mock: [createMockMMKV.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/createMMKV/createMockMMKV.ts) (used in tests)
- Nitro spec: [MMKVFactory.nitro.ts](https://github.com/mrousavy/react-native-mmkv/blob/main/packages/react-native-mmkv/src/specs/MMKVFactory.nitro.ts)
- Related: [crud-operations.md](./crud-operations.md), [encryption.md](./encryption.md)
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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall