rudder-js-sdk/skills/rudder-web-sdk/reference/storage.md

Storage — client.storage + client.projectStorage

Two key/value stores: per-player (StorageDomain, revision key storage) and project-wide shared (ProjectStorageDomain, revision key projectStorage). Sources: src/domains/StorageDomain.ts, src/domains/ProjectStorageDomain.ts.

Player storage

client.storage.data    // GetStorageResponse | undefined
await client.storage.save(items);
await client.storage.delete(type);

interface GetStorageResponse {
  items?: StorageItem[];
  nextCursor?: string;
}
interface StorageItem {
  data?: string;   // opaque payload, JSON-stringify yourself if needed
  id?: string;
  type?: string;   // the storage "collection" key
}

• save(items: StorageItem[]): Promise<void> — upserts items, then invalidates the domain so subscribers refetch.
• delete(type: string): Promise<void> — deletes all player storage items of that type, then invalidates.

Project storage

client.projectStorage.data   // GetProjectStorageResponse | undefined
await client.projectStorage.save(items);

interface GetProjectStorageResponse {
  items?: ProjectStorageItem[];
  nextCursor?: string;
}
interface ProjectStorageItem {
  data?: string;
  expiresAt?: string;
  id?: string;
  readPermission?: 'public' | 'serverOnly';
  size?: number;
  type?: string;
  updatedAt?: string;
  version?: number;
  writePermission?: 'public' | 'serverOnly';
}
interface ProjectStorageUpdateItem { data?: string; type?: string }

• save(items: ProjectStorageUpdateItem[]): Promise<void> — upserts, then invalidates. Writing is only possible for items whose writePermission is public; serverOnly items are read-only for clients.
• The SDK exposes no client-side project-storage delete.

Limits and notes

• Both domains load with { limit: 100 } — the observable snapshot holds at most 100 items and nextCursor pagination is not surfaced by the domain.
• data is a raw string on the wire; serialize/deserialize JSON yourself.
• Both are observable (SyncedState) and warmed by the revision poll only when in use; mutations self-invalidate.