Store and retrieve persistent data on the device using the starti.app Storage module

Storage and Data

This page walks you through using the starti.app storage APIs to persist data on the device. You will learn the difference between AppStorage and web localStorage, how to store and retrieve values, and how to manage storage safely.

AppStorage vs web localStorage

Your web app can already use window.localStorage, but it has limitations inside a native container:

Feature	`window.localStorage`	`startiapp.Storage.app` (AppStorage)
Persistence	Can be cleared by the OS under memory pressure	Stored natively — survives OS cache clearing
Size limit	~5 MB (browser-dependent)	Up to 50 MB total, 256 KB per value
Shared across domains	No (origin-scoped)	Yes — shared across all domains in the app
Async API	No (synchronous)	Yes (all methods return Promises)

AppStorage is the recommended choice when you need reliable persistence. It uses the native platform's storage system when the bridge is available, and falls back to localStorage in older app versions or during development in a regular browser.

You can check which storage backend is active by calling startiapp.Storage.app.isUsingNativeBridge(). It returns true when native storage is in use, and false when falling back to localStorage.

Store a value

Use setItem(key, value) to persist a string. Both the key and value must be strings.

await startiapp.Storage.app.setItem("user-preference", "dark-mode");

To store objects or arrays, serialize them to JSON first.

const settings = { theme: "dark", fontSize: 16, notifications: true };
await startiapp.Storage.app.setItem("settings", JSON.stringify(settings));

Retrieve a value

Use getItem(key) to read a stored value. It returns the string value, or null if the key does not exist.

const preference = await startiapp.Storage.app.getItem("user-preference");

if (preference !== null) {
  console.log("Preference:", preference);
} else {
  console.log("No preference saved yet.");
}

For JSON values, parse them after retrieval.

const raw = await startiapp.Storage.app.getItem("settings");

if (raw) {
  const settings = JSON.parse(raw);
  console.log("Theme:", settings.theme);
}

Remove a value

Use removeItem(key) to delete a single entry.

await startiapp.Storage.app.removeItem("user-preference");

Clear all AppStorage data

Use clear() to remove all entries stored through AppStorage.

await startiapp.Storage.app.clear();
console.log("All AppStorage data cleared.");

clear() removes all AppStorage data for the entire app, not just the current page. Use this with caution.

Size limits

AppStorage has the following limits:

Limit	Value
Maximum value size	256 KB per value
Maximum total storage	50 MB

If you need to store larger data (images, files), consider uploading to your server and storing only a URL or reference in AppStorage.

These limits apply to the native storage backend. If the SDK falls back to localStorage, the browser's own limits apply instead (typically around 5 MB).

Security note

AppStorage data is not encrypted. It is stored in plain text on the device. Do not use AppStorage for:

Passwords or secret keys
Authentication tokens (use the Auth integration's session management instead)
Personally identifiable information that requires encryption at rest

AppStorage is well suited for preferences, feature flags, cached display data, and other non-sensitive values.

Clearing all web data

The Storage integration also provides clearWebData(), which goes further than clear(). It wipes all web data the app has accumulated, including cookies, localStorage, cache, and session storage.

await startiapp.Storage.clearWebData();
console.log("All web data has been cleared.");

clearWebData() is a destructive operation. The user will be logged out of all web sessions, all cookies will be deleted, and all cached data will be gone. Use this for "reset app" or "clear cache" features — not for routine storage management.

Complete working example

Here is a full example that implements a simple settings panel backed by AppStorage.

const SETTINGS_KEY = "app-settings";

const defaultSettings = {
  theme: "light",
  fontSize: 14,
  notifications: true,
};

async function main() {
  if (!startiapp.isRunningInApp()) {
    console.log("Running in browser -- AppStorage will use localStorage fallback.");
  }

  try {
    await startiapp.initialize();
  } catch (e) {
    // Continue anyway -- AppStorage falls back to localStorage
  }

  // Load saved settings or use defaults
  const settings = await loadSettings();
  console.log("Current settings:", settings);

  // Update a setting
  settings.theme = "dark";
  await saveSettings(settings);
  console.log("Settings saved.");

  // Verify the save
  const reloaded = await loadSettings();
  console.log("Reloaded settings:", reloaded);
}

async function loadSettings() {
  const raw = await startiapp.Storage.app.getItem(SETTINGS_KEY);

  if (raw) {
    try {
      const parsed = JSON.parse(raw);
      return Object.assign({}, defaultSettings, parsed);
    } catch (e) {
      console.warn("Corrupt settings data -- using defaults.");
    }
  }

  return Object.assign({}, defaultSettings);
}

async function saveSettings(settings) {
  await startiapp.Storage.app.setItem(SETTINGS_KEY, JSON.stringify(settings));
}

// Wire up a "Reset all data" button
const resetBtn = document.getElementById("reset-btn");
if (resetBtn) {
  resetBtn.addEventListener("click", async function () {
    if (confirm("This will clear all app data. Continue?")) {
      await startiapp.Storage.app.clear();
      console.log("All AppStorage data cleared.");
      window.location.reload();
    }
  });
}

main();

Storage and Data

On this page