App Storage

A thin wrapper around react-native-mmkv with optional per-key expiration (TTL) and version-based invalidation.

Features

• Fast and efficient key-value storage powered by MMKV
• Optional TTL (Time To Live) for automatic key expiration
• Version-based invalidation: automatically expire data when the app version changes
• Automatic JSON serialization for objects and arrays
• Type-safe with TypeScript support
• Lightweight and easy to use

Installation

npm install @janiscommerce/app-storage

Peer Dependencies

npm install react-native-mmkv

Package	Required	Required for
react-native-mmkv	Yes	High-performance native storage engine
react	No (optional)	Required only when using the useStorageValue hook
@janiscommerce/app-device-info	No (optional)	App version for version-based invalidation (expireWithVersion)

Note: @janiscommerce/app-device-info is only needed if you use the expireWithVersion option. If not installed, all storage features work normally — version-based invalidation is simply disabled.

To enable version-based invalidation:

npm install @janiscommerce/app-device-info

Why peerDependency instead of dependency?

React Native only autolinks native modules located in the app's root node_modules. If these packages were installed as regular dependencies, they would be nested inside node_modules/@janiscommerce/app-storage/node_modules/, preventing autolinking and causing runtime errors.

Quick Start

import Storage from '@janiscommerce/app-storage';

// Create a storage instance
const storage = new Storage({ id: 'my-app-storage' });

// Store values
storage.set('token', 'abc123');
storage.set('user', { name: 'Jane', age: 30 });

// Retrieve values
const token = storage.get<string>('token'); // 'abc123'
const user = storage.get<{ name: string; age: number }>('user'); // { name: 'Jane', age: 30 }

// Remove a key
storage.remove('token');

// Clear all keys
storage.clear();

Usage with TTL (Time To Live)

import Storage from '@janiscommerce/app-storage';

const storage = new Storage();

// Store a value that expires in 5 minutes
storage.set('session-token', 'xyz789', { expiresAt: 5 });

// After 5 minutes, this will return null
const token = storage.get('session-token');

Usage with Version-based Invalidation

You can mark stored data to automatically expire when the app version changes. This is useful for cached data that should be refreshed after an app update (e.g., feature flags, remote config, API responses tied to a specific app version).

import Storage from '@janiscommerce/app-storage';

const storage = new Storage();

// Store a value that expires when the app version changes
storage.set('feature-flags', { darkMode: true, newUI: false }, { expireWithVersion: true });

// On the same app version, this returns the stored value
const flags = storage.get('feature-flags'); // { darkMode: true, newUI: false }

// After an app update (version change), this returns null
const staleFlags = storage.get('feature-flags'); // null (invalidated)

Combining TTL and Version-based Invalidation

Both options can be used together. The data will be invalidated if either condition is met: the TTL expires or the app version changes, whichever comes first.

import Storage from '@janiscommerce/app-storage';

const storage = new Storage();

// Expires after 60 minutes OR when the app version changes
storage.set('api-config', { baseUrl: 'https://api.example.com' }, {
  expiresAt: 60,
  expireWithVersion: true,
});

How it works

When expireWithVersion: true is passed to set(), the current app version (obtained from @janiscommerce/app-device-info) is saved alongside the value in its metadata. On get(), the stored version is compared against the current app version. If they differ, the key is invalidated and null is returned.

The version check is performed before the TTL check. This means version-invalidated data is cleaned up immediately, without waiting for the TTL to expire.

Multiple Storage Instances

You can create multiple isolated storage instances for different purposes:

import Storage from '@janiscommerce/app-storage';

const userStorage = new Storage({ id: 'user-data' });
const cacheStorage = new Storage({ id: 'cache' });
const sessionStorage = new Storage({ id: 'session' });

userStorage.set('profile', { name: 'John' });
cacheStorage.set('last-fetch', Date.now(), { expiresAt: 10 }); // expires in 10 minutes
sessionStorage.set('temp-data', { foo: 'bar' });

API Documentation

Storage

A thin wrapper around MMKV with optional per-key expiration (TTL) and version-based invalidation.

• Serializes objects/arrays to JSON on set.
• get() attempts JSON parse; otherwise returns string/number/boolean.
• Optional per-key expiration via expiresAt (minutes from now).
• Optional version-based invalidation via expireWithVersion.
• Expired or version-invalidated keys are automatically removed on get().
• remove() deletes the value and its expiration metadata.

Kind: global class Access: public

• Storage
  • new Storage(options)
  • .set(key, value, options)
  • .get(key) ⇒
  • .remove(key)
  • .clear()

new Storage(options)

Creates a new Storage instance.

Param	Description
options	Initialization options for the underlying MMKV instance.

storage.set(key, value, options)

Stores a value by key with optional expiration and version tracking.

Semantics:

• key null/undefined: no-op
• value null/undefined: no-op (null will not be stored; it is ignored)
• string/number/boolean are stored as string
• objects/arrays are serialized to JSON

Expiration:

• options.expiresAt: minutes from now until expiration. Stored under ${key}:__meta as an absolute timestamp in milliseconds.
• options.expireWithVersion: when true, the current app version is saved in metadata. On retrieval, if the stored version differs from the current version, the key is invalidated.

Kind: instance method of Storage

Param	Type	Description
key	string	The storage key.
value	unknown	The value to store.
options	object	Optional configuration.
options.expiresAt	number	Minutes from now until expiration.
options.expireWithVersion	boolean	If true, stores the current app version and invalidates the key when the version changes.

storage.get(key) ⇒

Retrieves a value by key. Returns null and cleans up stored data if any of these conditions are met:

• The stored app version differs from the current app version (version invalidation).
• The TTL has expired (time-based expiration).
• The metadata is corrupted or invalid.

Version check is performed before TTL check.

Kind: instance method of Storage Returns: Parsed JSON as T, or string/number/boolean; null if missing/expired/version-invalidated/invalid. Typeparam: T - Expected value type after JSON parse.

Param	Description
key	The storage key.

storage.remove(key)

Removes a key and its expiration metadata.

Kind: instance method of Storage

Param	Description
key	The storage key to remove.

storage.clear()

Clears all keys from the current MMKV instance.

Kind: instance method of Storage

useStorageValue

A React hook that subscribes to a storage key and returns its current value. Re-renders the component whenever the value changes.

Requires React as a peer dependency.

Signature

useStorageValue<T>(key: string, storage: Storage): T | null

Param	Type	Description
key	string	The storage key to observe.
storage	Storage	A Storage instance to read from and listen on.

Returns the current value for the key, or null if missing or expired.

Usage

import Storage, { useStorageValue } from '@janiscommerce/app-storage';

// Create a shared singleton instance
const appStorage = new Storage({ id: 'app-storage' });

// In your component
const MyComponent = () => {
    const userName = useStorageValue<string>('user-name', appStorage);

    return <Text>{userName ?? 'No name'}</Text>;
};

The hook re-renders automatically when appStorage.set('user-name', ...) is called from anywhere in the app — as long as all callers share the same Storage instance.

Important: use a shared instance

The hook receives a Storage instance directly. To get reactivity across components, all callers must share the same instance. The recommended pattern is to create a singleton and export it:

// storage.ts
import Storage from '@janiscommerce/app-storage';

export const appStorage = new Storage({ id: 'app-storage' });

// ComponentA.tsx — writes
appStorage.set('user-name', 'Fernando');

// ComponentB.tsx — reads and reacts
const name = useStorageValue<string>('user-name', appStorage); // re-renders on change

If each component creates its own new Storage(...) instance, they will not share listeners and writes won't trigger re-renders.

Use Cases

Recommended use cases for expireWithVersion

Use case	Why
Feature flags / remote config	Ensures stale flags from a previous version are not applied after an update.
Cached API responses	API contracts may change between app versions; cached responses could become incompatible.
Onboarding / tutorial state	After an update you may want to re-show onboarding for new features.
Computed or derived data	Cached computations that depend on app logic which may have changed.

NOT recommended for expireWithVersion

Use case	Why
User preferences (theme, language)	These should persist across updates. Use plain set() without expireWithVersion.
Authentication tokens	Tokens have their own expiration mechanisms. Use expiresAt instead.
User-generated content (drafts, notes)	Losing user data on update is a poor experience.
Data unrelated to app version	If the data does not depend on the app version, there is no reason to invalidate it.

Error Handling

Version retrieval failure

If getVersion() throws an error, the library degrades gracefully:

• On set() with expireWithVersion: true: If the version cannot be obtained, the appVersion field is not written to metadata. The value is still stored normally, and will behave as if expireWithVersion was not set.
• On get(): If the version cannot be obtained at read time but metadata contains an appVersion, the data is invalidated for safety. This prevents serving potentially incompatible cached data after an app update when version lookup temporarily fails. If metadata does not contain an appVersion, the value is returned normally (subject to TTL expiration if configured).

This ensures that errors during version lookup never cause data loss or crashes, while maintaining strict version validation when version tracking is enabled.

Corrupted metadata

If the metadata stored under ${key}:__meta is corrupted (invalid JSON), both the key and its metadata are deleted, and get() returns null. This prevents inconsistent state from persisting.

Backward Compatibility

This feature is fully backward compatible:

• Existing stored data (without appVersion in metadata) continues to work normally. The absence of appVersion is treated as "no version constraint" -- the key is never invalidated by version checks.
• The set() API remains unchanged for existing usage. The expireWithVersion option is purely additive; omitting it preserves the previous behavior.
• Metadata format is extended, not replaced. The __meta key now supports an optional appVersion field alongside the existing expiresAt field:

// Before (TTL only)
{ "expiresAt": 1700000000000 }

// After (TTL + version)
{ "expiresAt": 1700000000000, "appVersion": "2.1.0" }

// Version only (no TTL)
{ "appVersion": "2.1.0" }

Implementation Details

• The app version is obtained via DeviceInfo.getVersion() from @janiscommerce/app-device-info.
• Version comparison uses strict string equality (===). For example, "1.0.0" and "1.0.1" are considered different versions.
• The version string is stored as-is in the metadata. No semantic version parsing is performed.
• On get(), the validation order is: version check then TTL check. If the version is invalid, the key is removed immediately without evaluating TTL.
• The getAppVersion() helper is wrapped in a try-catch. Any exception results in a console.warn and a null return value, ensuring robust behavior even when the device info package is unavailable.

Author

Janis Commerce