Skip to main content

Storage.getItem

Asynchronously reads the string value at the given key. Resolves to null when the key is missing — distinct from an empty string ('').

Unofficial docs

This page is community-written. The SDK behavior itself is defined by the upstream @apps-in-toss/web-framework release.

Signature​

import { Storage } from '@apps-in-toss/web-framework';

declare const Storage: {
  getItem(key: string): Promise<string | null>;
  // ...see overview
};

Parameters​

NameTypeRequiredDescription
keystring✓The key to read. Must match exactly the key the mini-app wrote with setItem.

Returns​

  • Promise<string | null> — the stored string, or null if the key doesn't exist.
null ≠ empty string

null means the key was never written, or has been deleted via removeItem/clearItems. An empty string ('') is the result of explicitly storing an empty value — the two are distinct. Compare with value === null rather than !value (the latter swallows '').

Permission​

No permission required — the Storage namespace is not bound to a PermissionName. For the typical permission flow used by other namespaces, see Guides — Permissions pattern.

Examples​

Minimal​

import { Storage } from '@apps-in-toss/web-framework';

const lastSeen = await Storage.getItem('user.lastSeenScreen');
console.log(lastSeen ?? 'home'); // first visit → fall back to 'home'

Realistic — safely restoring a serialized object​

import { Storage } from '@apps-in-toss/web-framework';

interface UserPrefs {
  theme: 'light' | 'dark';
  language: string;
}

const DEFAULT_PREFS: UserPrefs = { theme: 'light', language: 'ko' };

async function loadPrefs(): Promise<UserPrefs> {
  const raw = await Storage.getItem('user.prefs');
  if (raw === null) return DEFAULT_PREFS;
  try {
    const parsed = JSON.parse(raw) as Partial<UserPrefs>;
    // Older versions may have only written some fields — fill in defaults.
    return { ...DEFAULT_PREFS, ...parsed };
  } catch {
    // Broken format or stale schema — fall back to defaults.
    return DEFAULT_PREFS;
  }
}

Try it live​

Open the Storage page in sdk-example and run the getItem card to inspect the result.

Open in sdk-example
  • Guides — Permissions pattern — permission flow used by other namespaces (reference only; Storage itself doesn't require a permission).
  • (coming soon) Recipes — "User preferences pattern (serialization, migration, defaults)"

External references​