---

name: client-storage description: Implement client-side storage patterns using localStorage, sessionStorage, or IndexedDB. Use for persisting user preferences, caching data, handling storage quota, and migrating stored data schemas.

Client Storage

When to Use This Skill

Use when you need to:

• Persist data in the browser (preferences, cache, state)
• Handle storage quota limits and errors
• Migrate data between schema versions
• Choose between localStorage, sessionStorage, or IndexedDB

Storage Selection Guide

Implementation Patterns

1. Basic localStorage with Error Handling

Copyfunction getItem<T>(key: string, defaultValue: T): T {
  try {
    const stored = localStorage.getItem(key);
    return stored ? JSON.parse(stored) : defaultValue;
  } catch {
    return defaultValue;
  }
}

function setItem<T>(key: string, value: T): boolean {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch (error) {
    if (error instanceof DOMException && error.name === 'QuotaExceededError') {
      console.warn('Storage quota exceeded');
    }
    return false;
  }
}

2. Versioned Config Pattern

Copytype Config = {
  version: number;
  // ... config fields
};

const CURRENT_VERSION = 2;

function migrateConfig(old: unknown): Config {
  const config = old as Record<string, unknown>;

  // v1 -> v2 migration
  if (!config.version || config.version < 2) {
    return {
      version: CURRENT_VERSION,
      // migrate fields...
    };
  }

  return config as Config;
}

function loadConfig(): Config {
  const stored = getItem('config', null);
  if (!stored) return DEFAULT_CONFIG;

  if (stored.version !== CURRENT_VERSION) {
    const migrated = migrateConfig(stored);
    setItem('config', migrated);
    return migrated;
  }

  return stored;
}

3. React Hook Pattern

Copyfunction useLocalStorage<T>(key: string, defaultValue: T) {
  const [value, setValue] = useState<T>(() =>
    getItem(key, defaultValue)
  );

  const setStoredValue = useCallback((newValue: T | ((prev: T) => T)) => {
    setValue(prev => {
      const resolved = newValue instanceof Function
        ? newValue(prev)
        : newValue;
      setItem(key, resolved);
      return resolved;
    });
  }, [key]);

  return [value, setStoredValue] as const;
}

4. IndexedDB for Large Data

Copyasync function openDB(name: string, version: number): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const request = indexedDB.open(name, version);

    request.onerror = () => reject(request.error);
    request.onsuccess = () => resolve(request.result);

    request.onupgradeneeded = (event) => {
      const db = request.result;
      // Create object stores during upgrade
      if (!db.objectStoreNames.contains('files')) {
        db.createObjectStore('files', { keyPath: 'id' });
      }
    };
  });
}

Quota Handling

Copyasync function checkStorageQuota(): Promise<{used: number; quota: number}> {
  if ('storage' in navigator && 'estimate' in navigator.storage) {
    const estimate = await navigator.storage.estimate();
    return {
      used: estimate.usage || 0,
      quota: estimate.quota || 0
    };
  }
  return { used: 0, quota: 0 };
}

Best Practices

1. Always wrap in try-catch - Storage can fail (private mode, quota)
2. Version your schemas - Enable smooth migrations
3. Use type guards - Validate data structure on load
4. Handle quota errors - Inform user, cleanup old data
5. Sync across tabs - Use storage event for multi-tab apps