localStorage and sessionStorage

1type Prefs = { v: 2; theme: 'light' | 'dark' | 'system'; reduceMotion: boolean }
2 
3const KEY = 'prefs'
4const DEFAULTS: Prefs = { v: 2, theme: 'system', reduceMotion: false }
5 
6// One synchronous read, at startup, before anything is animating.
7function load(): Prefs {
8  let raw: string | null = null
9  try {
10    raw = localStorage.getItem(KEY)
11  } catch {
12    return DEFAULTS // private window, or storage disabled entirely
13  }
14  if (!raw) return DEFAULTS
15  try {
16    const parsed = JSON.parse(raw) as Partial<Prefs>
17    if (parsed.v !== 2) return migrate(parsed) // written by an older build
18    return { ...DEFAULTS, ...parsed, v: 2 }
19  } catch {
20    return DEFAULTS // truncated or corrupted: recover, do not throw
21  }
22}
23 
24let prefs = load() // in memory from here on
25 
26let pending: number | undefined
27function save(next: Prefs, onFail: (e: unknown) => void) {
28  prefs = next
29  clearTimeout(pending)
30  pending = setTimeout(() => {
31    try {
32      localStorage.setItem(KEY, JSON.stringify(next))
33    } catch (e) {
34      onFail(e) // quota or disk: the user may need to know
35    }
36  }, 400) as unknown as number
37}
38 
39// The only cross-tab notification this API offers. It fires in OTHER tabs.
40addEventListener('storage', (e) => {
41  if (e.key === KEY && e.newValue) prefs = load()
42})

Three things are load-bearing: the read happens once, the parse can fail without taking startup with it, and the write failure reaches a caller that can decide what to do. The v field is what lets a build from six months ago hand data to a build from today.

• Input event dispatched — The task begins; nothing else runs on this thread until it ends
• localStorage.getItem — Blocking by contract — the thread waits for the store to answer
• JSON.parse of the value — Your code, on the main thread, scaling with payload size
• Style + layout — Cannot start until the task above completes
• Same handler, value already in memory — The read and the parse happened once, at startup
• Paint + composite → frame — Same pixels, and the input-to-frame path is a fraction of the work

The saving is not the storage call — it is the parse the storage call forced. That is why "cache the parsed value" beats "call storage less often".

input.addEventListener('input', () => {
  localStorage.setItem('draft', JSON.stringify(state))
})

// on load
const state = JSON.parse(localStorage.getItem('draft')!)

input.addEventListener('input', () => {
  scheduleSave(state) // debounced
})

function persist(state: Draft) {
  try {
    localStorage.setItem('draft', JSON.stringify({ v: 1, state }))
    lastSavedAt = Date.now()
  } catch (e) {
    // Do not swallow it: the user is about to lose work
    showBanner('Could not save your draft on this device.')
    report(e)
  }
}

// on load
const raw = safeGet('draft')
const draft = raw ? parseDraft(raw) ?? emptyDraft() : emptyDraft()

The left version writes synchronously on every keystroke, so it competes with rendering on the interaction the user is currently performing; it throws on quota with nothing catching it; and its non-null assertion turns a missing or corrupt value into a startup crash. The right version pays the storage cost once the user pauses, tells them when persistence failed rather than pretending it worked, and treats a bad value as an empty draft instead of an exception.