Storage

Nebula provides isolated key-value storage for each miniapp, backed by native host storage. It is suitable for user preferences, cached data, and other lightweight persistent state.

Storage limits

Each miniapp is limited to 10 MB of storage.
Storage is isolated by appId, so miniapps cannot see each other's data.

High-level APIs

Use the high-level APIs when you want automatic JSON serialization and deserialization:

import { setStorage, getStorage, getStorageInfo } from '@nebula-rn/client';

await setStorage({ key: 'user', data: { name: 'Zhang San', age: 28 } });

const user = await getStorage<{ name: string; age: number }>('user');
console.log(user.name);

const info = await getStorageInfo();
console.log(info.keys);
console.log(info.currentSize);
console.log(info.limitSize);

setStorage

await setStorage({ key: string, data: unknown }): Promise<void>

getStorage

const value = await getStorage<T>(key: string): Promise<T>

If the key does not exist, the API throws. Use try/catch when needed.

getStorageInfo

const info = await getStorageInfo(): Promise<GetStorageInfoResult>

type GetStorageInfoResult = {
  keys: string[];
  currentSize: number;
  limitSize: number;
};

Low-level APIs

Low-level APIs operate directly on string values and do not serialize automatically:

import {
  getStorageItem,
  setStorageItem,
  removeStorageItem,
  clearStorageItems,
  getStorageKeys,
  getStorageCurrentSize,
} from '@nebula-rn/client';

setStorageItem / getStorageItem

await setStorageItem('token', 'abc123');
const token = await getStorageItem('token');

getStorageItem returns undefined when the key does not exist.

removeStorageItem

await removeStorageItem('token');

clearStorageItems

await clearStorageItems();

getStorageKeys

const keys = await getStorageKeys();

getStorageCurrentSize

const sizeKB = await getStorageCurrentSize();

Serialization helpers

import { serializeStorageValue, deserializeStorageValue } from '@nebula-rn/client';

const json = serializeStorageValue({ count: 42 });
const obj = deserializeStorageValue<{ count: number }>(json);

Common patterns

const selectCity = async (city: string) => {
  await setStorageItem('selectedCity', city);
  Miniapp.navigateBack(1);
};

usePageOnShow(async () => {
  const city = await getStorageItem('selectedCity');
  if (city) setCity(city);
});

Cache with a TTL

async function setCacheWithTTL(key: string, data: unknown, ttlMs: number) {
  await setStorage({
    key,
    data: { value: data, expiry: Date.now() + ttlMs },
  });
}

async function getCacheWithTTL<T>(key: string): Promise<T | null> {
  try {
    const cached = await getStorage<{ value: T; expiry: number }>(key);
    if (Date.now() > cached.expiry) {
      await removeStorageItem(key);
      return null;
    }
    return cached.value;
  } catch {
    return null;
  }
}

Notes

Storage is persistent across miniapp restarts.
Storage operations are asynchronous, so always use await.
High-level APIs serialize JSON automatically, while low-level APIs operate on raw strings.
Do not store sensitive information such as passwords or secrets.
Writes fail once the 10 MB limit has been exceeded.

On this page