React layer     : current render snapshot used to paint UI
Storage layer   : durable serialized value outside React

Where is a serialized copy stored?

Who owns this value?
Who may mutate it?
Is it canonical or only a cache?
What invalidates it?
How long may it live?
What version is its schema?
What happens if parsing fails?
What happens in another tab?
What happens during SSR/hydration?

Small preference? localStorage.
Tab-only draft? sessionStorage.
Large/offline structured data? IndexedDB.
Canonical business state? server.
Secret credential? do not store in JS-accessible storage.

canonical client preference
cache of server data
draft not yet committed
session-local workflow state
feature behavior hint

theme preference
table density
sidebar collapsed state
last selected local tab
editor layout preference

current account role
permissions
billing status
case enforcement status
approval result
server mutation result

theme: light | dark | system
density: compact | comfortable
sidebarCollapsed: boolean
tableColumnOrder: string[]

small
non-sensitive
user-owned
low-frequency updates
safe to default if missing

unsent comment draft
multi-step wizard draft
local note draft
search filter draft before commit

Should it survive tab close?
Should it expire after 24 hours?
Should it be cleared after submit?
Should it be scoped by user id, tenant id, resource id, or route?

draft:comment

app:v2:tenant:{tenantId}:user:{userId}:case:{caseId}:comment-draft

dismissed onboarding banner
dismissed release note
dismissed migration warning

dismissed:release-note:2026-07-state-redesign

dismissedReleaseNote

idempotency key
retry policy
conflict resolution
visibility to the user
encryption/privacy policy if sensitive
server reconciliation

const isAdmin = localStorage.getItem('role') === 'admin';

const cachedCapabilities = readCachedCapabilities();

Client permission state may improve UX.
Server permission checks enforce truth.

mouse position
scroll position updated every frame
input value persisted on every keystroke without debounce
animation state
large editor document on every character

filters
settings
draft
user

acme-app:v3:user:{userId}:table:{tableId}:columns
acme-app:v2:tenant:{tenantId}:case:{caseId}:comment-draft
acme-app:v1:ui:theme

function useLocalStorageState<T>(key: string, initialValue: T) {
  const [value, setValue] = React.useState<T>(() => {
    const raw = window.localStorage.getItem(key);
    return raw == null ? initialValue : JSON.parse(raw);
  });

  React.useEffect(() => {
    window.localStorage.setItem(key, JSON.stringify(value));
  }, [key, value]);

  return [value, setValue] as const;
}

breaks on server because window is unavailable
throws if JSON is corrupt
has no schema validation
has no migration
writes after every value change
has no expiration
has no cross-tab synchronization
can hydrate differently from server markup
does not handle storage quota/security errors

type PersistedEnvelope<T> = {
  version: number;
  createdAt: string;
  updatedAt: string;
  expiresAt?: string;
  value: T;
};

Can this value still be trusted?
Can this schema still be read?
Should this value be deleted?
When was it last written?

type DecodeResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: 'missing' | 'expired' | 'invalid-json' | 'invalid-schema' | 'unsupported-version' };

function decodeEnvelope<T>(
  raw: string | null,
  options: {
    version: number;
    validate: (value: unknown) => value is T;
    migrate?: (envelope: PersistedEnvelope<unknown>) => PersistedEnvelope<T> | null;
    now?: () => Date;
  }
): DecodeResult<T> {
  if (raw == null) return { ok: false, reason: 'missing' };

  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return { ok: false, reason: 'invalid-json' };
  }

  if (!isEnvelope(parsed)) {
    return { ok: false, reason: 'invalid-schema' };
  }

  const envelope = parsed as PersistedEnvelope<unknown>;
  const now = options.now?.() ?? new Date();

  if (envelope.expiresAt && new Date(envelope.expiresAt) <= now) {
    return { ok: false, reason: 'expired' };
  }

  if (envelope.version !== options.version) {
    const migrated = options.migrate?.(envelope);
    if (!migrated) return { ok: false, reason: 'unsupported-version' };
    if (!options.validate(migrated.value)) return { ok: false, reason: 'invalid-schema' };
    return { ok: true, value: migrated.value };
  }

  if (!options.validate(envelope.value)) {
    return { ok: false, reason: 'invalid-schema' };
  }

  return { ok: true, value: envelope.value };
}

function isEnvelope(value: unknown): value is PersistedEnvelope<unknown> {
  if (typeof value !== 'object' || value === null) return false;
  const record = value as Record<string, unknown>;
  return (
    typeof record.version === 'number' &&
    typeof record.createdAt === 'string' &&
    typeof record.updatedAt === 'string' &&
    'value' in record
  );
}

SSR-safe initialization
parse failure
schema validation
version envelope
debounced persistence
storage write errors
reset

type PersistentStateOptions<T> = {
  key: string;
  version: number;
  initialValue: T | (() => T);
  validate: (value: unknown) => value is T;
  storage?: Storage;
  debounceMs?: number;
  expiresInMs?: number;
  onDecodeError?: (reason: string) => void;
  onWriteError?: (error: unknown) => void;
};

function resolveInitial<T>(value: T | (() => T)): T {
  return typeof value === 'function' ? (value as () => T)() : value;
}

function createEnvelope<T>(
  value: T,
  version: number,
  expiresInMs?: number
): PersistedEnvelope<T> {
  const now = new Date();
  return {
    version,
    createdAt: now.toISOString(),
    updatedAt: now.toISOString(),
    expiresAt: expiresInMs ? new Date(now.getTime() + expiresInMs).toISOString() : undefined,
    value,
  };
}

export function usePersistentState<T>(options: PersistentStateOptions<T>) {
  const {
    key,
    version,
    initialValue,
    validate,
    debounceMs = 150,
    expiresInMs,
    onDecodeError,
    onWriteError,
  } = options;

  const storage = options.storage ?? (typeof window !== 'undefined' ? window.localStorage : undefined);

  const [state, setState] = React.useState<T>(() => {
    const fallback = resolveInitial(initialValue);
    if (!storage) return fallback;

    const decoded = decodeEnvelope(storage.getItem(key), { version, validate });
    if (!decoded.ok) {
      if (decoded.reason !== 'missing') onDecodeError?.(decoded.reason);
      return fallback;
    }

    return decoded.value;
  });

  const reset = React.useCallback(() => {
    setState(resolveInitial(initialValue));
    try {
      storage?.removeItem(key);
    } catch (error) {
      onWriteError?.(error);
    }
  }, [initialValue, key, onWriteError, storage]);

  React.useEffect(() => {
    if (!storage) return;

    const timer = window.setTimeout(() => {
      try {
        storage.setItem(
          key,
          JSON.stringify(createEnvelope(state, version, expiresInMs))
        );
      } catch (error) {
        onWriteError?.(error);
      }
    }, debounceMs);

    return () => window.clearTimeout(timer);
  }, [debounceMs, expiresInMs, key, onWriteError, state, storage, version]);

  return [state, setState, reset] as const;
}

function ThemeLabel() {
  const theme = window.localStorage.getItem('theme') ?? 'light';
  return <span>{theme}</span>;
}

function ThemeLabel() {
  const [theme, setTheme] = React.useState<'light' | 'dark' | null>(null);

  React.useEffect(() => {
    const raw = window.localStorage.getItem('app:v1:theme');
    setTheme(raw === 'dark' ? 'dark' : 'light');
  }, []);

  if (theme === null) return null;
  return <span>{theme}</span>;
}

store preference in localStorage
run a tiny inline script before React loads
set html class/data-theme immediately
let React adopt the already-applied theme

function createStorageStore<T>(options: {
  key: string;
  defaultValue: T;
  parse: (raw: string | null) => T;
  serialize: (value: T) => string;
}) {
  return {
    getSnapshot() {
      return options.parse(window.localStorage.getItem(options.key));
    },
    getServerSnapshot() {
      return options.defaultValue;
    },
    subscribe(listener: () => void) {
      const onStorage = (event: StorageEvent) => {
        if (event.key === options.key) listener();
      };
      window.addEventListener('storage', onStorage);
      return () => window.removeEventListener('storage', onStorage);
    },
    set(value: T) {
      window.localStorage.setItem(options.key, options.serialize(value));
      window.dispatchEvent(new StorageEvent('storage', { key: options.key }));
    },
  };
}

If user changes theme in tab A, should tab B update?
If user logs out in tab A, should tab B react?
If draft changes in tab A, should tab B overwrite local draft?

React.useEffect(() => {
  function handleStorage(event: StorageEvent) {
    if (event.key !== key) return;
    setState(readValueFromStorage());
  }

  window.addEventListener('storage', handleStorage);
  return () => window.removeEventListener('storage', handleStorage);
}, [key]);

const channel = new BroadcastChannel('app-state');
channel.postMessage({ type: 'theme/changed', value: 'dark' });

app:v1:case-search-filters

app:v1:user:{userId}:tenant:{tenantId}:case-search-filters

function clearUserScopedStorage(userId: string) {
  const prefix = `app:v1:user:${userId}:`;

  for (let i = window.localStorage.length - 1; i >= 0; i--) {
    const key = window.localStorage.key(i);
    if (key?.startsWith(prefix)) {
      window.localStorage.removeItem(key);
    }
  }
}

React state changed -> write serialized snapshot to storage
Storage changed externally -> update React state

const [firstName, setFirstName] = usePersistentState('first', '');
const [lastName, setLastName] = usePersistentState('last', '');
const [fullName, setFullName] = usePersistentState('full', '');

React.useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

const fullName = `${firstName} ${lastName}`;

type Theme = 'light' | 'dark' | 'system';

function isTheme(value: unknown): value is Theme {
  return value === 'light' || value === 'dark' || value === 'system';
}

function useThemePreference() {
  return usePersistentState<Theme>({
    key: 'learn-react:v1:ui:theme',
    version: 1,
    initialValue: 'system',
    validate: isTheme,
  });
}

type TableLayout = {
  columnOrder: string[];
  hiddenColumns: string[];
  density: 'compact' | 'comfortable';
};

function tableLayoutKey(userId: string, tableId: string) {
  return `learn-react:v2:user:${userId}:table:${tableId}:layout`;
}

type CommentDraft = {
  body: string;
  attachments: Array<{ localId: string; name: string }>;
};

function commentDraftKey(userId: string, caseId: string) {
  return `learn-react:v1:user:${userId}:case:${caseId}:comment-draft`;
}

resetDraft();

query key compatibility
cache age
stale time
garbage collection
mutation invalidation
schema drift
network reconciliation

A feature changed, but old users see broken UI because old storage values still load.

No versioning, migration, or invalidation.

Use namespaced versioned keys or envelope version migration.

Server renders default UI, client immediately renders stored value, React warns or flickers.

Use stable server fallback, client-only hydration, cookie/bootstrap script, or useSyncExternalStore server snapshot.

User can modify storage and unlock UI behavior.

Treat client permission state as UX hint only. Enforce on server.

User B sees User A's filters, drafts, or layout on shared device.

Scope keys by user/tenant or clear on logout.

Typing becomes janky after adding persistence.

Large synchronous JSON serialization on every keystroke.

Debounce, batch, move large data to IndexedDB, avoid high-frequency writes.

App crashes on startup for one user.

JSON.parse throws during lazy initializer.

Safe decode with fallback and storage cleanup.

Two tabs edit same draft and one silently overwrites the other.

Add updatedAt, conflict detection, active-tab warning, or avoid cross-tab draft sharing.

missing value uses fallback
valid value loads
invalid JSON falls back
invalid schema falls back
expired value falls back and optionally clears
version migration works
write error does not crash UI
reset removes storage
logout clears user-scoped keys
storage event updates subscriber
same-tab update notifies local subscriber

it('falls back when storage contains invalid json', () => {
  localStorage.setItem('app:v1:theme', '{');

  const result = decodeEnvelope(localStorage.getItem('app:v1:theme'), {
    version: 1,
    validate: isTheme,
  });

  expect(result).toEqual({ ok: false, reason: 'invalid-json' });
});

Is this value safe to store in JS-accessible browser storage?
Is it client-owned, server-owned, or only a draft?
What is the retention policy?
What key namespace scopes it?
Does it need user/tenant/resource scoping?
What is the schema version?
What happens if the value is missing?
What happens if it is corrupt?
What happens if it is old?
What happens across tabs?
What happens during SSR/hydration?
What happens on logout?
What is the performance cost of serialization?

React state is the render snapshot.
Browser storage is a serialized external system.
Persistence is synchronization.
Stored data needs namespace, schema, retention, validation, and invalidation.
Security-sensitive and server-owned data must not rely on JS-accessible storage as authority.